# SoloTerm Docs MCP

Remote MCP server for SoloTerm/Solo documentation, built on Cloudflare Workers with the Agents SDK MCP handler and a Code Mode-style tool surface.

The `/mcp` endpoint exposes only two JavaScript-oriented tools:

- `search`: run a JavaScript async arrow function against the generated `docs` array. The code runs in an isolated Dynamic Worker with outbound network access blocked.
- `execute`: run a JavaScript async arrow function against `soloterm.request()`. The code runs in an isolated Dynamic Worker whose outbound access is restricted to `https://soloterm.com/api/v1/docs` and child routes.

There are no legacy docs tools or MCP resources. `?codemode=false` is intentionally ignored so clients always receive the same `search` and `execute` tools.

## Generated Docs

The docs snapshot is generated into `src/generated/docs.ts` from `https://soloterm.com/api/v1/docs`.

The Code Mode declarations shown in tool descriptions are generated into `src/generated/code-mode-types.ts` by the same generator. They define the in-sandbox `docs`, `generatedAt`, `sourceBaseUrl`, and `soloterm.request()` API.

At runtime, `search` uses a cached live docs snapshot. The Worker refreshes that cache hourly with a Cloudflare scheduled trigger (`0 * * * *`) and also refreshes on cache miss. If the live docs API is unavailable during refresh, the generated static snapshot remains as a fallback.

Coverage is verified against two live sources:

- The docs API link graph starting at `https://soloterm.com/api/v1/docs`.
- Public docs URLs listed in `https://soloterm.com/sitemap.xml`.

`npm run docs:verify` refreshes the snapshot, crawls the live API graph, reads the sitemap, and fails unless the generated slugs exactly cover the union of both indexes.

## Development

```bash
npm install
npm run docs:fetch
npm run docs:verify
npm run build
npm run dev
MCP_URL=http://localhost:8787 npm run test:mcp
```

The local MCP endpoint is served at:

```text
http://localhost:8787/mcp
```

## Live Worker

```text
https://soloterm-docs-mcp.sdf-ecosystem.workers.dev/mcp
```

## Deploy

```bash
npm run deploy
```

After deploy, connect MCP clients to:

```text
https://soloterm-docs-mcp.<your-subdomain>.workers.dev/mcp
```