feat: agents mcp #643

mattzcarey · 2025-11-08T22:07:49Z

loads from Github, caches chunks in KV for 1 day.
uses stemming to do a fuzzy keyword match.

changeset-bot · 2025-11-08T22:07:53Z

⚠️ No Changeset found

Latest commit: 502eb95

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

pkg-pr-new · 2025-11-08T22:10:09Z

Open in StackBlitz

npm i https://pkg.pr.new/cloudflare/agents@643

commit: 502eb95

claude · 2025-11-08T22:41:38Z

Claude Code Review

Critical Issues

1. Missing KV namespace ID in wrangler.jsonc (site/agents/wrangler.jsonc:10-13)

The kv_namespaces binding lacks an id field required for production deployment
This will fail when deploying: wrangler deploy needs either id or preview_id
Add: "id": "your-kv-namespace-id" to the binding

2. Top-level await breaks ES module compatibility (site/agents/src/server/utils.ts:26-29)

const chunker = await RecursiveChunker.create(...) at module scope causes initialization issues
Workers with top-level await can have cold start problems and race conditions
Move chunker creation into fetchAndBuildIndex or lazy-initialize on first use

3. Environment access pattern is fragile (site/agents/src/server/utils.ts:3,40,126)

import { env } from "cloudflare:workers" followed by direct env.DOCS_KV access bypasses proper DI
This breaks testability and doesn't match Workers' execution model
The env should be passed as parameter from the fetch handler

Minor Issues

4. No test coverage

New MCP server functionality has no tests
Consider adding unit tests for search formatting and integration tests for the tool

5. Error messages lose context (site/agents/src/server/index.ts:58-67)

Generic "try again later" message doesn't help users debug issues
Consider surfacing error type (rate limit vs. cache miss vs. search failure)

6. Index rebuild on every request when cache miss (site/agents/src/server/utils.ts:139-171)

If KV cache expires, every request will rebuild the entire index from GitHub
No mutex/lock prevents concurrent expensive rebuilds
Consider using Durable Objects or a rebuild queue for cache warming

threepointone

will review in detail later, this is exciting but I need to finish my slides haha

threepointone · 2025-11-12T12:03:01Z

site/agents/src/server/index.ts

+    inputSchema
+  },
+  async ({ query, k }) => {
+    const searchEffect = Effect.gen(function* () {


sneaking in effect huh

threepointone · 2025-11-12T12:07:46Z

site/agents-mcp/package.json

+    "types": "wrangler types"
+  },
+  "dependencies": {
+    "@cfworker/json-schema": "^4.1.1",


this won't be necessary if we land https://github.com/cloudflare/agents/pull/620/files#diff-0b2ee78feb201d3caa4914dcbf17821b7a21d6e5d0f708fc2eadcf7ee8f83c38R28

threepointone · 2025-11-12T12:08:50Z

site/agents/src/server/index.ts

+  },
+  async ({ query, k }) => {
+    const searchEffect = Effect.gen(function* () {
+      console.log({ query, k });


i'd kinda like to have some logging on the queries are being asked. We need to instrument the server properly but I added this till then.

threepointone · 2025-11-18T12:49:11Z

site/agents/src/server/index.ts

+export default {
+  async fetch(request: Request, env: Env, ctx: ExecutionContext) {
+    return createMcpHandler(mcpServer)(request, env, ctx);
+  }


can make a scheduled worker here and run this everyday

threepointone · 2025-11-19T03:18:47Z

@mattzcarey can you check whether I've broken anything? if it looks good I'll land and ship

threepointone · 2025-11-19T03:19:50Z

site/agents/src/server/utils.ts

+const CHUNK_SIZE = 2000;
+const MIN_CHARS_PER_CHUNK = 500;
+
+const chunker = await RecursiveChunker.create({


hmm I'm not sure this works in prod...

apparently it does

Adds documentation for the new Agents SDK Documentation MCP server that provides token-efficient search of Cloudflare Agents SDK documentation. Related to cloudflare/agents#643 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

threepointone · 2025-11-19T03:22:04Z

📚 Documentation sync

A documentation PR has been created to sync these changes:

Docs PR: feat: agents mcp cloudflare-docs#26617

The documentation updates include:

Added Agents SDK Documentation MCP server to the catalog
Documented the search tool and usage patterns
Added information about caching and rate limiting

cc @cloudflare/docs-team

threepointone · 2025-11-19T12:43:46Z

📚 Documentation sync status

✅ Documentation has been synced to cloudflare-docs#26617

This PR adds the Agents SDK Documentation MCP server to the catalog of Cloudflare-managed MCP servers.

This is an automated comment from the documentation sync workflow

mattzcarey · 2025-11-19T12:44:34Z

Looks good!! :) can test it at https://agents-site.mattzcarey.workers.dev/mcp

* feat: agents mcp * more effect and stemming * add readme * add note about ratelimiting * move it all into the site app * Update package-lock.json * fix: add main entrypoint and node compat --------- Co-authored-by: Sunil Pai <[email protected]>

threepointone reviewed Nov 12, 2025

View reviewed changes

threepointone reviewed Nov 18, 2025

View reviewed changes

mattzcarey and others added 6 commits November 19, 2025 03:17

feat: agents mcp

c93ff57

more effect and stemming

a626534

add readme

bcfb0e7

add note about ratelimiting

6da496f

move it all into the site app

861abad

Update package-lock.json

a758ed3

threepointone force-pushed the feat-agents-mcp branch from 003e3e6 to a758ed3 Compare November 19, 2025 03:18

threepointone reviewed Nov 19, 2025

View reviewed changes

threepointone mentioned this pull request Nov 19, 2025

feat: agents mcp cloudflare/cloudflare-docs#26617

Open

fix: add main entrypoint and node compat

502eb95

threepointone merged commit 4e285b2 into main Nov 19, 2025
5 checks passed

threepointone deleted the feat-agents-mcp branch November 19, 2025 13:12

feat: agents mcp #643

feat: agents mcp #643

Uh oh!

Conversation

mattzcarey commented Nov 8, 2025

Uh oh!

changeset-bot bot commented Nov 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚠️ No Changeset found

Uh oh!

pkg-pr-new bot commented Nov 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

claude bot commented Nov 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Claude Code Review

Critical Issues

Minor Issues

Uh oh!

threepointone left a comment

Choose a reason for hiding this comment

Uh oh!

threepointone Nov 12, 2025

Choose a reason for hiding this comment

Uh oh!

threepointone Nov 12, 2025

Choose a reason for hiding this comment

Uh oh!

threepointone Nov 12, 2025

Choose a reason for hiding this comment

Uh oh!

mattzcarey Nov 12, 2025

Choose a reason for hiding this comment

Uh oh!

threepointone Nov 18, 2025

Choose a reason for hiding this comment

Uh oh!

threepointone commented Nov 19, 2025

Uh oh!

threepointone Nov 19, 2025

Choose a reason for hiding this comment

Uh oh!

threepointone Nov 19, 2025

Choose a reason for hiding this comment

Uh oh!

threepointone commented Nov 19, 2025

📚 Documentation sync

Uh oh!

threepointone commented Nov 19, 2025

Uh oh!

mattzcarey commented Nov 19, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

changeset-bot bot commented Nov 8, 2025 •

edited

Loading

pkg-pr-new bot commented Nov 8, 2025 •

edited

Loading

claude bot commented Nov 8, 2025 •

edited

Loading