{"_id":"@act-spec/mcp-server","name":"@act-spec/mcp-server","dist-tags":{"rc":"0.2.0-rc.1","latest":"0.2.0-rc.1"},"versions":{"0.2.0-rc.1":{"name":"@act-spec/mcp-server","version":"0.2.0-rc.1","description":"Universal MCP server for any ACT-emitting site. Point at a URL; expose ACT tools to any MCP-capable agent.","license":"Apache-2.0","author":{"name":"Jeremy Forsythe","email":"jeremy@act-spec.org"},"homepage":"https://act-spec.org","bugs":{"url":"https://github.com/act-spec/act/issues"},"type":"module","main":"./dist/index.js","module":"./dist/index.js","types":"./dist/index.d.ts","bin":{"act-mcp-server":"bin/act-mcp-server.js"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","default":"./dist/index.js"}},"publishConfig":{"access":"public"},"repository":{"type":"git","url":"git+https://github.com/act-spec/act.git","directory":"packages/mcp-server"},"dependencies":{"@modelcontextprotocol/sdk":"^1.29.0","@act-spec/inspector":"0.2.0-rc.1","@act-spec/core":"0.2.0-rc.1"},"devDependencies":{"@vitest/coverage-v8":"^2.1.9","tsx":"^4.19.2","typescript":"^5.6.3","vitest":"^2.1.4"},"scripts":{"build":"tsc -p tsconfig.json","test":"vitest run","test:watch":"vitest","test:coverage":"vitest run --coverage","lint":"eslint src","typecheck":"tsc -p tsconfig.json --noEmit"},"_id":"@act-spec/mcp-server@0.2.0-rc.1","_integrity":"sha512-9c/LEBXD4/ibs9y0rOPB1c7GHdfan4Gl+qPGHKclAlfWQfbQ+lswfd4EZJIp+oC+uioPfaQBvUYIn/dp69qZDw==","_resolved":"/private/var/folders/yp/y7frhcvj70jgr6b8g633lghr0000gn/T/a166fe9876fea9aba6146df784f8549d/act-spec-mcp-server-0.2.0-rc.1.tgz","_from":"file:act-spec-mcp-server-0.2.0-rc.1.tgz","_nodeVersion":"22.19.0","_npmVersion":"11.6.0","dist":{"integrity":"sha512-9c/LEBXD4/ibs9y0rOPB1c7GHdfan4Gl+qPGHKclAlfWQfbQ+lswfd4EZJIp+oC+uioPfaQBvUYIn/dp69qZDw==","shasum":"d2c5462752bf96ef5c796efb5bc64649474f6ed8","tarball":"https://registry.npmjs.org/@act-spec/mcp-server/-/mcp-server-0.2.0-rc.1.tgz","fileCount":56,"unpackedSize":187207,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCvQL1PK0PwRroMM+aQKSaJdxD4RKdig003GrREX2mAJQIgSf8oqxaVoKEfUio4Dwpey2C5hjek2qxseMXqma4xgO8="}]},"_npmUser":{"name":"jdforsythe","email":"jdforsythe@gmail.com"},"directories":{},"maintainers":[{"name":"jdforsythe","email":"jdforsythe@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mcp-server_0.2.0-rc.1_1777915316364_0.9072359125539367"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-04T17:21:56.235Z","0.2.0-rc.1":"2026-05-04T17:21:56.508Z","modified":"2026-05-04T17:21:56.780Z"},"maintainers":[{"name":"jdforsythe","email":"jdforsythe@gmail.com"}],"description":"Universal MCP server for any ACT-emitting site. Point at a URL; expose ACT tools to any MCP-capable agent.","homepage":"https://act-spec.org","repository":{"type":"git","url":"git+https://github.com/act-spec/act.git","directory":"packages/mcp-server"},"author":{"name":"Jeremy Forsythe","email":"jeremy@act-spec.org"},"bugs":{"url":"https://github.com/act-spec/act/issues"},"license":"Apache-2.0","readme":"# @act-spec/mcp-server\n\nUniversal MCP server for any [ACT](https://act-spec.org)-emitting site.\nPoint it at a URL; expose ACT tools to any MCP-capable agent (Claude\nDesktop, Cursor, Continue, …) over stdio.\n\n## What it is\n\nMost ACT sites are static — a `.well-known/act.json` manifest pointing\nat an index and per-node JSON files. AI agents that don't natively\nspeak ACT can still browse those sites if you put a thin MCP shim in\nfront. That's what this package is.\n\nThe server is stateless and universal: it doesn't ship its own content,\nit just fetches whatever ACT site the user (or the agent's\nconfiguration) points it at.\n\n## Status\n\nACT v0.1 internal hand-test candidate. Public release lands at v0.2.\n\n## Quick start\n\n```sh\nnpx @act-spec/mcp-server https://act-spec.org\n```\n\nThe optional positional URL becomes the default site for tool calls\nthat omit `url`. Without it, every tool call must supply `url`\nexplicitly.\n\n## Claude Desktop\n\nAdd this to `claude_desktop_config.json`\n(`~/Library/Application Support/Claude/claude_desktop_config.json` on\nmacOS):\n\n```jsonc\n{\n  \"mcpServers\": {\n    \"act-spec\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@act-spec/mcp-server\", \"https://act-spec.org\"]\n    }\n  }\n}\n```\n\nRestart Claude Desktop. The four tools (`act_load_site`,\n`act_walk_subtree`, `act_get_node`, `act_search`) appear in the tool\npicker.\n\n## Cursor\n\n`~/.cursor/mcp.json`:\n\n```jsonc\n{\n  \"mcpServers\": {\n    \"act-spec\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@act-spec/mcp-server\", \"https://act-spec.org\"]\n    }\n  }\n}\n```\n\n## Tool reference\n\n### `act_load_site(url)`\n\nFetches `<url>/.well-known/act.json` and returns the parsed manifest\nplus any structural findings.\n\n- `url` *(string, required when no default site is configured)* —\n  origin or any URL on the site.\n\nReturns `{ url, manifest, findings }`.\n\n### `act_walk_subtree(url, node_id, depth?)`\n\nWalks descendants of `node_id` up to `depth` levels (default 3, max 8).\nUseful for browsing a documentation section without fetching the whole\ntree.\n\n- `url` *(string)*\n- `node_id` *(string, required)*\n- `depth` *(number, optional, default 3, clamped to `[0, 8]`)*\n\nReturns `{ url, root_id, depth, nodes, truncated, findings }` where\neach node is `{ id, type, parent, children, title?, summary? }`.\n\n### `act_get_node(url, node_id)`\n\nFetches a single ACT node envelope by id.\n\n- `url` *(string)*\n- `node_id` *(string, required)*\n\nReturns `{ url, node, findings }`.\n\n### `act_search(url, query)`\n\nCase-insensitive substring search across `title`, `summary`, and prose\nblocks in `content[]`.\n\n- `url` *(string)*\n- `query` *(string, required)*\n\nReturns `{ url, query, hits, truncated, findings }` where each hit is\n`{ id, type, title, matched_in: 'title' | 'summary' | 'body', excerpt? }`.\n\n## Limitations\n\n`act_search` is a deliberately naive implementation:\n\n- Substring match only. No tokenization, no stemming.\n- No relevance ranking. Hits appear in walk order.\n- No operators, no quoting, no fuzzy matching.\n- It walks the entire index and fetches every node body that doesn't\n  match on title or summary. On large sites this is slow.\n\nIf your producer advertises a `search_url_template` (Strict conformance\nlevel), prefer their endpoint directly. A future release will route\nthrough it transparently when present.\n\n## Self-hosting\n\nFor a self-hosted deployment that does NOT use this npm package, point\nclients at a hosted MCP endpoint instead — see\n`examples/hybrid-static-runtime-mcp/` in this repo. The hosted endpoint\nruns the same code in a Cloudflare Worker.\n\n## Hosted alternative\n\nThe reference impl runs at `mcp.act-spec.org` (Streamable HTTP). Any\nMCP-capable agent that supports remote servers can connect without a\nlocal install.\n","readmeFilename":"README.md","_rev":"1-de70b997070b524c6ae360a46631547b"}