Skip to content

Commit 6d29be8

Browse files
aninibreadaninibread
authored
Update the docs-vectorize to use AI Search as backend (cloudflare#249)
* Added an MCP for docs-ai-search to use AI Search as backend * use new stateless architecture in docs-ai-search. * update registerDocsTools calls * remove vectorize references * added ai-search prompt file and removed vectorize references
1 parent 0df3a67 commit 6d29be8

File tree

16 files changed

+6384
-7
lines changed

16 files changed

+6384
-7
lines changed

‎apps/docs-ai-search/.eslintrc.cjs‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
/** @type {import("eslint").Linter.Config} */
2+
module.exports = {
3+
root: true,
4+
extends: ['@repo/eslint-config/default.cjs'],
5+
}

‎apps/docs-ai-search/CHANGELOG.md‎

Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
# docs-ai-search
2+
3+
## 0.5.0
4+
5+
### Minor Changes
6+
7+
- Changed backend from Vectorize to AI Search for documentation search
8+
- Now uses Cloudflare AI Search (AutoRAG) for contextual search of the Cloudflare Developer Documentation
9+
- Maintains full backward compatibility - same XML response format and tool interface
10+
- Package renamed from `docs-vectorize` to `docs-ai-search` to reflect the new backend
11+
12+
## 0.4.3
13+
14+
### Patch Changes
15+
16+
- Updated dependencies [7fc3f18]
17+
- @repo/mcp-common@0.20.1
18+
19+
## 0.4.2
20+
21+
### Patch Changes
22+
23+
- 847fc1f: Update cloudflare-oauth-handler
24+
- Updated dependencies [f9f0bb6]
25+
- Updated dependencies [847fc1f]
26+
- @repo/mcp-common@0.20.0
27+
- @repo/mcp-observability@0.32.4
28+
29+
## 0.4.1
30+
31+
### Patch Changes
32+
33+
- 43f493d: Update agent + modelcontextprotocol deps
34+
- Updated dependencies [43f493d]
35+
- @repo/mcp-observability@0.32.3
36+
- @repo/mcp-common@0.19.3
37+
38+
## 0.4.0
39+
40+
### Minor Changes
41+
42+
- dee0a7b: Updated the model for docs search to embeddinggemma-300m
43+
44+
## 0.3.3
45+
46+
### Patch Changes
47+
48+
- 24dd872: feat: Add MCP tool titles and hints to all Cloudflare tools
49+
- Updated dependencies [24dd872]
50+
- @repo/mcp-common@0.19.2
51+
52+
## 0.3.2
53+
54+
### Patch Changes
55+
56+
- 7422e71: Update MCP sdk
57+
- Updated dependencies [7422e71]
58+
- @repo/mcp-observability@0.32.2
59+
- @repo/mcp-common@0.19.1
60+
61+
## 0.3.1
62+
63+
### Patch Changes
64+
65+
- cc6d41f: Update agents deps & modelcontextprotocol
66+
- Updated dependencies [1833c6d]
67+
- Updated dependencies [cc6d41f]
68+
- @repo/mcp-common@0.19.0
69+
- @repo/mcp-observability@0.32.1
70+
71+
## 0.3.0
72+
73+
### Minor Changes
74+
75+
- f885d07: Add search docs tool to bindings and obs servers
76+
77+
### Patch Changes
78+
79+
- Updated dependencies [f885d07]
80+
- @repo/mcp-common@0.18.0
81+
82+
## 0.2.1
83+
84+
### Patch Changes
85+
86+
- Updated dependencies [83e2d19]
87+
- @repo/mcp-common@0.17.1
88+
89+
## 0.2.0
90+
91+
### Minor Changes
92+
93+
- 89bfaf4: feat: add Pages to Workers migration guide to docs-vectorize MCP server
94+
95+
## 0.1.0
96+
97+
### Minor Changes
98+
99+
- 6cf52a6: Support AOT tokens
100+
101+
### Patch Changes
102+
103+
- 0fc4439: Update agents and modelcontext dependencies
104+
- Updated dependencies [6cf52a6]
105+
- Updated dependencies [0fc4439]
106+
- @repo/mcp-observability@0.32.0
107+
- @repo/mcp-common@0.17.0
108+
109+
## 0.0.4
110+
111+
### Patch Changes
112+
113+
- 3677a18: Remove extraneous log
114+
- Updated dependencies [3677a18]
115+
- @repo/mcp-common@0.16.3
116+
117+
## 0.0.3
118+
119+
### Patch Changes
120+
121+
- Updated dependencies [86c2e4f]
122+
- @repo/mcp-common@0.16.2
123+
124+
## 0.0.2
125+
126+
### Patch Changes
127+
128+
- cf3771b: chore: add suffixes to common files in apps and packages
129+
130+
It can be confusing switching between 16 files named 'index.ts', or 3 files named workers.ts. This change renames common files to have suffixes such as .types.ts, .api.ts, etc. to make it easier to work across files in the monorepo.
131+
132+
- Updated dependencies [cf3771b]
133+
- @repo/mcp-common@0.16.1
134+
- @repo/mcp-observability@0.31.1

‎apps/docs-ai-search/README.md‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
# Cloudflare Documentation MCP Server (via AI Search) 🔭
2+
3+
This is a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) server that supports remote MCP connections. It uses Cloudflare AI Search (AutoRAG) to provide contextual search of the Cloudflare Developer Documentation.
4+
5+
The Cloudflare account this worker is deployed on has an AI Search instance configured with the complete Cloudflare Developer Documentation.
6+
7+
## 🔨 Available Tools
8+
9+
Currently available tools:
10+
11+
| **Category** | **Tool** | **Description** |
12+
| ---------------------------- | --------------------------------- | ------------------------------------ |
13+
| **Cloudflare Documentation** | `search_cloudflare_documentation` | Search the Cloudflare documentation. |
14+
15+
### Prompt Examples
16+
17+
- `Do Cloudflare Workers costs depend on response sizes? I want to serve some images (map tiles) from an R2 bucket and I'm concerned about costs.`
18+
- `How many indexes are supported in Workers Analytics Engine? Give an example using the Workers binding api.`
19+
- `Can you give me some information on how to use the Workers AI Search binding`
20+
21+
## Access the remote MCP server from any MCP Client
22+
23+
If your MCP client has first class support for remote MCP servers, the client will provide a way to accept the server URL (`https://docs.mcp.cloudflare.com`) directly within its interface (for example in [Cloudflare AI Playground](https://playground.ai.cloudflare.com/)).
24+
25+
If your client does not yet support remote MCP servers, you will need to set up its respective configuration file using [mcp-remote](https://www.npmjs.com/package/mcp-remote) to specify which servers your client can access.
26+
27+
Replace the content with the following configuration:
28+
29+
```json
30+
{
31+
"mcpServers": {
32+
"cloudflare": {
33+
"command": "npx",
34+
"args": ["mcp-remote", "https://docs.mcp.cloudflare.com/mcp"]
35+
}
36+
}
37+
}
38+
```
39+
40+
Once you've set up your configuration file, restart MCP client and a browser window will open showing your OAuth login page. Proceed through the authentication flow to grant the client access to your MCP server. After you grant access, the tools will become available for you to use.
41+
42+
Interested in contributing, and running this server locally? See [CONTRIBUTING.md](CONTRIBUTING.md) to get started.

‎apps/docs-ai-search/package.json‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
{
2+
"name": "docs-ai-search",
3+
"version": "0.4.3",
4+
"private": true,
5+
"scripts": {
6+
"check:lint": "run-eslint-workers",
7+
"check:types": "run-tsc",
8+
"deploy": "run-wrangler-deploy",
9+
"dev": "wrangler dev",
10+
"start": "npm run dev",
11+
"types": "wrangler types --include-env=false",
12+
"test": "vitest run"
13+
},
14+
"dependencies": {
15+
"@cloudflare/workers-oauth-provider": "0.0.13",
16+
"@hono/zod-validator": "0.4.3",
17+
"@modelcontextprotocol/sdk": "1.20.2",
18+
"@repo/mcp-common": "workspace:*",
19+
"@repo/mcp-observability": "workspace:*",
20+
"agents": "0.2.19",
21+
"cloudflare": "4.2.0",
22+
"hono": "4.7.6",
23+
"mime": "4.0.6",
24+
"zod": "3.24.2"
25+
},
26+
"devDependencies": {
27+
"@cloudflare/vitest-pool-workers": "0.8.14",
28+
"@types/node": "22.14.1",
29+
"prettier": "3.5.3",
30+
"typescript": "5.5.4",
31+
"vitest": "3.0.9",
32+
"wrangler": "4.10.0"
33+
}
34+
}

‎apps/docs-ai-search/src/docs-ai-search.app.ts‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
import { createMcpHandler, McpAgent } from 'agents/mcp'
2+
3+
import { getEnv } from '@repo/mcp-common/src/env'
4+
import { registerPrompts } from '@repo/mcp-common/src/prompts/docs-ai-search.prompts'
5+
import { initSentry } from '@repo/mcp-common/src/sentry'
6+
import { CloudflareMCPServer } from '@repo/mcp-common/src/server'
7+
import { registerDocsTools } from '@repo/mcp-common/src/tools/docs-ai-search.tools'
8+
9+
import type { Env } from './docs-ai-search.context'
10+
11+
const env = getEnv<Env>()
12+
13+
export class CloudflareDocumentationMCP extends McpAgent<Env, never, never> {
14+
_server: CloudflareMCPServer | undefined
15+
set server(server: CloudflareMCPServer) {
16+
this._server = server
17+
}
18+
get server(): CloudflareMCPServer {
19+
if (!this._server) {
20+
throw new Error('Tried to access server before it was initialized')
21+
}
22+
return this._server
23+
}
24+
25+
constructor(
26+
public ctx: DurableObjectState,
27+
public env: Env
28+
) {
29+
super(ctx, env)
30+
}
31+
32+
async init() {
33+
this.server = createMcpServer(env, this.ctx)
34+
}
35+
}
36+
37+
const sseHandler = CloudflareDocumentationMCP.serveSSE('/sse')
38+
39+
export default {
40+
fetch: async (req: Request, env: Env, ctx: ExecutionContext) => {
41+
const url = new URL(req.url)
42+
if (url.pathname === '/sse' || url.pathname === '/sse/message') {
43+
return sseHandler.fetch(req, env, ctx)
44+
}
45+
if (url.pathname === '/mcp') {
46+
const server = createMcpServer(env, ctx, req)
47+
const mcpHandler = createMcpHandler(server)
48+
return mcpHandler(req, env, ctx)
49+
}
50+
return new Response('Not found', { status: 404 })
51+
},
52+
}
53+
54+
function createMcpServer(
55+
env: Env,
56+
ctx: {
57+
waitUntil: ExecutionContext['waitUntil']
58+
},
59+
req?: Request
60+
) {
61+
const sentry = initSentry(env, ctx, req)
62+
63+
const server = new CloudflareMCPServer({
64+
wae: env.MCP_METRICS,
65+
serverInfo: {
66+
name: env.MCP_SERVER_NAME,
67+
version: env.MCP_SERVER_VERSION,
68+
},
69+
sentry,
70+
})
71+
72+
registerDocsTools(server, env)
73+
registerPrompts(server)
74+
75+
return server
76+
}

‎apps/docs-ai-search/src/docs-ai-search.context.ts‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
import type { CloudflareDocumentationMCP } from './docs-ai-search.app'
2+
3+
export interface Env {
4+
ENVIRONMENT: 'development' | 'staging' | 'production'
5+
MCP_SERVER_NAME: string
6+
MCP_SERVER_VERSION: string
7+
MCP_OBJECT: DurableObjectNamespace<CloudflareDocumentationMCP>
8+
MCP_METRICS: AnalyticsEngineDataset
9+
SENTRY_ACCESS_CLIENT_ID: string
10+
SENTRY_ACCESS_CLIENT_SECRET: string
11+
GIT_HASH: string
12+
SENTRY_DSN: string
13+
AI: Ai
14+
}

‎apps/docs-ai-search/tsconfig.json‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
{
2+
"extends": "@repo/typescript-config/workers.json",
3+
"include": ["*/**.ts", "./vitest.config.ts"]
4+
}

‎apps/docs-ai-search/vitest.config.ts‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
import { defineWorkersConfig } from '@cloudflare/vitest-pool-workers/config'
2+
3+
import type { Env } from './src/docs-ai-search.context'
4+
5+
export interface TestEnv extends Env {
6+
CLOUDFLARE_MOCK_ACCOUNT_ID: string
7+
CLOUDFLARE_MOCK_API_TOKEN: string
8+
}
9+
10+
export default defineWorkersConfig({
11+
test: {
12+
poolOptions: {
13+
workers: {
14+
wrangler: { configPath: `${__dirname}/wrangler.jsonc` },
15+
miniflare: {
16+
bindings: {
17+
CLOUDFLARE_MOCK_ACCOUNT_ID: 'mock-account-id',
18+
CLOUDFLARE_MOCK_API_TOKEN: 'mock-api-token',
19+
} satisfies Partial<TestEnv>,
20+
},
21+
},
22+
},
23+
},
24+
})

0 commit comments

Comments
 (0)