Merge pull request #67 from cloudflare/csparks/autorag-mcp

Add a cloudflare docs MCP server using autorag

Author: cmsparks

apps/docs-autorag/.dev.vars.example

@@ -0,0 +1,5 @@
+/** @type {import("eslint").Linter.Config} */
+module.exports = {
+	root: true,
+	extends: ['@repo/eslint-config/default.cjs'],
+}

apps/docs-autorag/.eslintrc.cjs

@@ -0,0 +1,21 @@
+# Model Context Protocol (MCP) Server + Cloudflare Documentation (via Autorag)
+
+This is a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) server that supports remote MCP connections. It connects to an autorag instance (in this case, Cloudflare docs)
+
+To run this server, you'll need access to an autorag instance which has indexed the contents of cloudflare-docs: https://github.com/cloudflare/cloudflare-docs/
+
+The Cloudflare account this worker is deployed on already has this Autorag instance setup and indexed.
+
+## Running locally
+
+```
+pnpm run start
+```
+
+Then connect to the server via remote MCP at `http://localhost:8976/sse`
+
+## Deploying
+
+```
+pnpm run deploy --env [ENVIRONMENT]
+```

apps/docs-autorag/README.md

@@ -0,0 +1,33 @@
+{
+	"name": "docs-autorag",
+	"version": "0.0.1",
+	"private": true,
+	"scripts": {
+		"check:lint": "run-eslint-workers",
+		"check:types": "run-tsc",
+		"deploy": "wrangler deploy",
+		"dev": "wrangler dev",
+		"start": "wrangler dev",
+		"cf-typegen": "wrangler types",
+		"test": "vitest run"
+	},
+	"dependencies": {
+		"@cloudflare/workers-oauth-provider": "0.0.2",
+		"@hono/zod-validator": "0.4.3",
+		"@modelcontextprotocol/sdk": "1.9.0",
+		"@repo/mcp-common": "workspace:*",
+		"agents": "0.0.62",
+		"cloudflare": "4.2.0",
+		"hono": "4.7.6",
+		"mime": "^4.0.6",
+		"zod": "3.24.2"
+	},
+	"devDependencies": {
+		"@cloudflare/vitest-pool-workers": "0.8.14",
+		"@cloudflare/workers-types": "4.20250410.0",
+		"prettier": "3.5.3",
+		"typescript": "5.5.4",
+		"vitest": "3.0.9",
+		"wrangler": "4.10.0"
+	}
+}

apps/docs-autorag/package.json

@@ -0,0 +1,29 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { McpAgent } from 'agents/mcp'
+
+import { registerDocsTools } from './tools/docs'
+
+// The docs MCP server isn't stateful, so we don't have state/props
+export type Props = never
+
+export type State = never
+
+export class CloudflareDocumentationMCP extends McpAgent<Env, State, Props> {
+	server = new McpServer({
+		name: 'Remote MCP Server with Cloudflare Documentation',
+		version: '1.0.0',
+	})
+
+	constructor(
+		public ctx: DurableObjectState,
+		public env: Env
+	) {
+		super(ctx, env)
+	}
+
+	async init() {
+		registerDocsTools(this)
+	}
+}
+
+export default CloudflareDocumentationMCP.mount('/sse')

apps/docs-autorag/src/index.ts

@@ -0,0 +1,76 @@
+import { type EmbeddedResource } from '@modelcontextprotocol/sdk/types.js'
+import mime from 'mime'
+import { z } from 'zod'
+
+import type { CloudflareDocumentationMCP } from '../index'
+
+/**
+ * Registers the docs search tool with the MCP server
+ * @param agent The MCP server instance
+ */
+export function registerDocsTools(agent: CloudflareDocumentationMCP) {
+	// Register the worker logs analysis tool by worker name
+	agent.server.tool(
+		'search_cloudflare_documentation',
+		`Search the Cloudflare documentation. 
+		
+		You should use this tool when:
+		- A user asks questions about Cloudflare products (Workers, Developer Platform, Zero Trust, CDN, etc)
+		- A user requests information about a Cloudflare feature
+		- You are unsure of how to use some Cloudflare functionality
+		- You are writing Cloudflare Workers code and need to look up Workers-specific documentation
+
+		This tool returns a number of results from a vector database. These are embedded as resources in the response and are plaintext documents in a variety of formats.
+		`,
+		{
+			// partially pulled from autorag query optimization example
+			query: z.string().describe(`Search query. The query should:
+1. Identify the core concepts and intent
+2. Add relevant synonyms and related terms
+3. Remove irrelevant filler words
+4. Structure the query to emphasize key terms
+5. Include technical or domain-specific terminology if applicable`),
+			scoreThreshold: z
+				.number()
+				.min(0)
+				.max(1)
+				.optional()
+				.describe('A score threshold (0-1) for which matches should be included.'),
+			maxNumResults: z
+				.number()
+				.default(10)
+				.optional()
+				.describe('The maximum number of results to return.'),
+		},
+		async (params) => {
+			// we don't need "rewrite query" OR aiSearch because an LLM writes the query and formats the output for us.
+			const result = await agent.env.AI.autorag(agent.env.AUTORAG_NAME).search({
+				query: params.query,
+				ranking_options: params.scoreThreshold
+					? {
+							score_threshold: params.scoreThreshold,
+						}
+					: undefined,
+				max_num_results: params.maxNumResults,
+			})
+
+			const resources: EmbeddedResource[] = result.data.map((result) => {
+				const content = result.content.reduce((acc, contentPart) => {
+					return acc + contentPart.text
+				}, '')
+				return {
+					type: 'resource',
+					resource: {
+						uri: `docs://${result.filename}`,
+						mimeType: mime.getType(result.filename) ?? 'text/plain',
+						text: content,
+					},
+				}
+			})
+
+			return {
+				content: resources,
+			}
+		}
+	)
+}

apps/docs-autorag/src/tools/docs.ts

@@ -0,0 +1,4 @@
+{
+	"extends": "@repo/typescript-config/workers.json",
+	"include": ["*/**.ts", "./vitest.config.ts"]
+}

apps/docs-autorag/tsconfig.json

@@ -0,0 +1,22 @@
+import { defineWorkersConfig } from '@cloudflare/vitest-pool-workers/config'
+
+export interface TestEnv extends Env {
+	CLOUDFLARE_MOCK_ACCOUNT_ID: string
+	CLOUDFLARE_MOCK_API_TOKEN: string
+}
+
+export default defineWorkersConfig({
+	test: {
+		poolOptions: {
+			workers: {
+				wrangler: { configPath: `${__dirname}/wrangler.jsonc` },
+				miniflare: {
+					bindings: {
+						CLOUDFLARE_MOCK_ACCOUNT_ID: 'mock-account-id',
+						CLOUDFLARE_MOCK_API_TOKEN: 'mock-api-token',
+					} satisfies Partial<TestEnv>,
+				},
+			},
+		},
+	},
+})