Skip to main content

mcp.soubiran.dev

mcp.soubiran.dev gives assistants access to my public English and French content. It exposes three read-only tools for topic discovery, complete Markdown retrieval, and exact metadata queries.

The TypeScript Worker uses the Model Context Protocol SDK and the Cloudflare Agents MCP handler. Requests to /mcp reach the server. Other paths redirect to soubiran.dev. The handler does not require authentication.

One content catalog, two locales

The server loads the website's /pages.en.json and /pages.fr.json feeds in parallel. PAGES_EN_URL and PAGES_FR_URL configure their locations. Zod validates the records, and the loader combines them into one pages array.

Each record has a stable ID, locale, content type, title, published URL, and markdownUrl. Descriptions, dates, and translation links are optional. Relative URLs are resolved against the feed URL. Duplicate IDs across the combined feeds cause an error rather than selecting one document arbitrarily.

The website catalog covers pages, posts, talks, series, series articles, and infrastructure documentation. talks.soubiran.dev supplies talk content to the website during its build. The MCP reads the resulting website documents through the same catalog as the rest of the content.

Publication stays with the website. The MCP fetches metadata and follows the supplied Markdown URLs; it does not maintain another document store.

Search, retrieve, or query

search_content

This tool accepts a natural-language query and searches the soubiran-dev Cloudflare AI Search instance. Search and catalog loading run in parallel. Retrieval requests up to 20 results with a match threshold of 0.6 and reranks them with @cf/baai/bge-reranker-base.

The server matches each search chunk's metadata ID to a catalog record. It returns the score, excerpt, source key, and page metadata, including the published URL for citations. Chunks without a matching catalog entry are omitted.

Search finds relevant content, but ranking does not establish which page is newest. Exact date comparisons belong in list_pages, and an assistant should read the full document with get_page before summarizing it.

get_page

This tool accepts an exact stable ID, resolves it in the combined catalog, and fetches its markdownUrl. It returns the complete document as text. An unknown ID or failed upstream request produces an MCP tool error.

A talk document can include its summary, event details, resource links, and transcript. The website composes that Markdown, so retrieval works the same way for a talk, post, or infrastructure page.

list_pages

This tool accepts a single asynchronous JavaScript arrow function. The function can read the combined pages array to filter by locale or type, match titles, compare dates, count records, or group metadata. It does not search document bodies.

For example, this query returns the five most recent dated English posts with the fields needed for retrieval and citation:

async () => pages
  .filter(page => page.locale === 'en' && page.type === 'post' && page.date)
  .sort((a, b) => b.date.localeCompare(a.date))
  .slice(0, 5)
  .map(({ id, title, date, url }) => ({ id, title, date, url }))

Returning only the relevant records and fields reduces how much metadata enters the model's context. Both discovery tools return IDs that get_page can resolve.

Isolated code execution

list_pages uses Code Mode to answer metadata questions without a separate tool for every filter or aggregation. Acorn parses the submitted code and checks that it is one asynchronous arrow function. Input is limited to 20,000 characters.

Worker Loader runs the function in a temporary Worker with a recursively frozen copy of pages. The Worker has no secrets, storage, or application bindings. Network access is disabled with globalOutbound: null, and the executor also disables fetch, WebSocket, and EventSource.

Execution has a 50 ms CPU limit and permits no subrequests. The function must return a JSON-serializable value, and the server rejects results larger than 256 KiB. Query failures become tool errors rather than failing the MCP request handler.

Deployment and observability

Wrangler deploys the server to Cloudflare Workers with an AI Search namespace binding and a Worker Loader binding. The MCP handler uses a configurable allowed CORS origin.

Cloudflare persists logs and traces. Sentry captures exceptions, with user information and HTTP body collection disabled. Evlog records request duration, tool outcomes, selected upstream timings, result counts, and response sizes. Submitted query code is not logged. Redaction rules cover input and output payloads, queries, document content, excerpts, Markdown, authorization headers, and cookies.

The interactive diagram loads in your browser. Its contents are also available as a list.

Read diagram as a list
  • Cloudflare Workers, deployment

    Expose the MCP server at `/mcp` and redirect other paths to the personal website.

    • Wrangler, build

      Deploy the TypeScript Worker with Wrangler.

    • GitHub, repository

      Host the Worker source, content tools, and deployment configuration.

      • Model Context Protocol SDK, stack

        Define the server, tool inputs, and protocol responses.

      • Cloudflare Agents, stack

        Handle MCP requests at the Worker's `/mcp` endpoint.

      • Zod, stack

        Validate localized page catalogs and tool inputs.

      • Acorn, stack

        Parse query code and require a single asynchronous arrow function.

    • Cloudflare AI Search, data

      Search the `soubiran-dev` instance through the `AI_SEARCH` namespace binding.

    • Cloudflare Worker Loader, runtime

      Execute metadata queries in temporary Workers with network access disabled.

  • Localized page catalogs and Markdown, data

    Load `pages.en.json` and `pages.fr.json`, then retrieve documents through each record's `markdownUrl`.

    • soubiran.dev, website, producer

      Publish pages, posts, series, talks, and infrastructure documentation in a shared content catalog.

  • Sentry, monitoring

    Capture request and tool exceptions without collecting user information or HTTP bodies.

  • Evlog, monitoring

    Record structured request and tool outcomes with sensitive content redacted.

What do you think?

Discussions

Loading discussions...

Add a comment

Checking your session...