feat: agents mcp

[mattzcarey]

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

[changeset-bot]

⚠️ No Changeset found

Latest commit: 412cb13

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]

Open in StackBlitz

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

commit: 412cb13

[claude]

Claude Code Review

Issues Found

1. Missing KV namespace binding configuration (site/agents-mcp/wrangler.jsonc:7-10)
The KV namespace is declared without an id field. This will fail deployment unless the namespace already exists and is bound via wrangler config/secrets.

"kv_namespaces": [
  {
    "binding": "DOCS_KV"
    // Missing: "id": "<namespace-id>"
  }
]

2. Global state mutation risk (site/agents-mcp/src/utils.ts:26-29)
The chunker is created with top-level await, which could cause initialization issues if RecursiveChunker.create() is async. Consider moving this into the Effect pipeline or lazy initialization.

3. Missing error handling for KV operations (site/agents-mcp/src/utils.ts:124-127)
getCachedDocs doesn't handle cases where KV binding is unavailable (e.g., during local dev without --remote). Should gracefully fall back to fetching from GitHub.

4. No tests
No test coverage for the search logic, chunking, caching, or error scenarios. This is critical for a production MCP server.

5. Incomplete TODO (site/agents-mcp/src/index.ts:9)
// TODO: instrument this server for observability - Consider if this should be addressed before merge.

Minor/Style

• The package-lock.json changes show many dependencies being marked as non-peer when they appear to be transitive deps - verify this is intentional
• worker-configuration.d.ts (10k+ lines) appears to be a generated file that probably shouldn't be committed

[threepointone]

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

[threepointone]

sneaking in effect huh

[threepointone]

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

[threepointone]

stray log?

[mattzcarey]

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.