{"_id":"@agentailor/mcp","_rev":"2-8324a2371388247af179cc2f08ef1066","name":"@agentailor/mcp","dist-tags":{"latest":"0.2.0"},"versions":{"0.1.0":{"name":"@agentailor/mcp","version":"0.1.0","keywords":["mcp","model-context-protocol","agentailor","fastmcp","ai","llm"],"license":"Apache-2.0","_id":"@agentailor/mcp@0.1.0","maintainers":[{"name":"ibjunior","email":"contact@agentailor.com"}],"homepage":"https://github.com/agentailor/agentailor-mcp#readme","bugs":{"url":"https://github.com/agentailor/agentailor-mcp/issues"},"bin":{"agentailor-mcp":"dist/index.stdio.js"},"dist":{"shasum":"2f711a69e347c7b82a9f7ddf6189e8697a3c3c83","tarball":"https://registry.npmjs.org/@agentailor/mcp/-/mcp-0.1.0.tgz","fileCount":23,"integrity":"sha512-5CmtVJ+pLHXSADNHMgovruTJYHHoeWTvRoagdcH4YSDS+EGNPaMDjSAj9aR3o9K0eGRhuLacF2fbwVDznJ6LZA==","signatures":[{"sig":"MEQCIDEQFG3xX9y/QAMyEnyj44p44o2sSJotFne3FCBTjFudAiANsBk6qkeFmrHQZbRABOq7j6mzl3jaVA7Eg2XQPhXerA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":40421},"main":"dist/index.stdio.js","type":"module","_from":"file:agentailor-mcp-0.1.0.tgz","types":"./dist/index.stdio.d.ts","engines":{"node":">=20"},"scripts":{"test":"vitest run","build":"tsc -p tsconfig.build.json","format":"prettier --write .","inspect":"mcp-inspector http://localhost:3000/mcp","dev:http":"tsx watch src/index.http.ts","dev:stdio":"tsx watch src/index.stdio.ts","typecheck":"tsc --noEmit","start:http":"node dist/index.http.js","test:watch":"vitest","start:stdio":"node dist/index.stdio.js","format:check":"prettier --check .","inspect:stdio":"mcp-inspector --cli node dist/index.stdio.js --method tools/list"},"_npmUser":{"name":"ibjunior","email":"contact@agentailor.com"},"_resolved":"/tmp/af4c7745d4024c92e07715ecc24c1362/agentailor-mcp-0.1.0.tgz","_integrity":"sha512-5CmtVJ+pLHXSADNHMgovruTJYHHoeWTvRoagdcH4YSDS+EGNPaMDjSAj9aR3o9K0eGRhuLacF2fbwVDznJ6LZA==","repository":{"url":"git+https://github.com/agentailor/agentailor-mcp.git","type":"git"},"_npmVersion":"10.8.2","description":"MCP server for Agentailor — search the blog and read articles and open-source repo docs over the Model Context Protocol.","directories":{},"_nodeVersion":"20.20.2","dependencies":{"zod":"^4.4.3","dotenv":"^17.4.2","fastmcp":"^4.3.2"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.22.4","vitest":"^4.1.9","prettier":"^3.9.4","typescript":"^6.0.3","@types/node":"^26.0.0","@modelcontextprotocol/inspector":"^0.22.0"},"_npmOperationalInternal":{"tmp":"tmp/mcp_0.1.0_1783001385023_0.7850170927600642","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@agentailor/mcp","version":"0.2.0","description":"MCP server for Agentailor — search the blog and read articles and open-source repo docs over the Model Context Protocol.","type":"module","license":"Apache-2.0","main":"dist/index.stdio.js","bin":{"agentailor-mcp":"dist/index.stdio.js"},"keywords":["mcp","model-context-protocol","agentailor","fastmcp","ai","llm"],"homepage":"https://github.com/agentailor/mcp#readme","repository":{"type":"git","url":"git+https://github.com/agentailor/mcp.git"},"bugs":{"url":"https://github.com/agentailor/mcp/issues"},"publishConfig":{"access":"public"},"dependencies":{"dotenv":"^17.4.2","fastmcp":"^4.3.2","zod":"^4.4.3"},"devDependencies":{"@modelcontextprotocol/inspector":"^0.22.0","@types/node":"^26.0.0","prettier":"^3.9.4","tsx":"^4.22.4","typescript":"^6.0.3","vitest":"^4.1.9"},"engines":{"node":">=20"},"scripts":{"build":"tsc -p tsconfig.build.json","dev:stdio":"tsx watch src/index.stdio.ts","dev:http":"tsx watch src/index.http.ts","start:stdio":"node dist/index.stdio.js","start:http":"node dist/index.http.js","test":"vitest run","test:watch":"vitest","typecheck":"tsc --noEmit","format":"prettier --write .","format:check":"prettier --check .","inspect":"mcp-inspector http://localhost:3000/mcp","inspect:stdio":"mcp-inspector --cli node dist/index.stdio.js --method tools/list"},"_id":"@agentailor/mcp@0.2.0","types":"./dist/index.stdio.d.ts","_integrity":"sha512-uMzlfefhyWWnU3gn+WIgOCT3Y0Ch4xPgFa4n4oinlNbJLwAq5oyvptOi1Vz2Rb+RYhrpC/NC5bfYEkxKybi7AQ==","_resolved":"/tmp/3c425b0ef5c18bcc995d6e9e1863eddf/agentailor-mcp-0.2.0.tgz","_from":"file:agentailor-mcp-0.2.0.tgz","_nodeVersion":"20.20.2","_npmVersion":"10.8.2","dist":{"integrity":"sha512-uMzlfefhyWWnU3gn+WIgOCT3Y0Ch4xPgFa4n4oinlNbJLwAq5oyvptOi1Vz2Rb+RYhrpC/NC5bfYEkxKybi7AQ==","shasum":"a25219f5b5a2565dc87cc69e3445508e9ff969d7","tarball":"https://registry.npmjs.org/@agentailor/mcp/-/mcp-0.2.0.tgz","fileCount":23,"unpackedSize":42460,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIBWCcXRr5GqX/jNBUokOZ6r8PbMdVSlBkzyxauyrlMFOAiB3rVQMpTwOa/dI90gh+fmCcdbo7UlmQGm0VLBrJ0dQiQ=="}]},"_npmUser":{"name":"ibjunior","email":"contact@agentailor.com"},"directories":{},"maintainers":[{"name":"ibjunior","email":"contact@agentailor.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mcp_0.2.0_1783108351762_0.11533772668454523"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-02T14:09:44.908Z","modified":"2026-07-03T19:52:32.035Z","0.1.0":"2026-07-02T14:09:45.161Z","0.2.0":"2026-07-03T19:52:31.920Z"},"bugs":{"url":"https://github.com/agentailor/mcp/issues"},"license":"Apache-2.0","homepage":"https://github.com/agentailor/mcp#readme","keywords":["mcp","model-context-protocol","agentailor","fastmcp","ai","llm"],"repository":{"type":"git","url":"git+https://github.com/agentailor/mcp.git"},"description":"MCP server for Agentailor — search the blog and read articles and open-source repo docs over the Model Context Protocol.","maintainers":[{"name":"ibjunior","email":"contact@agentailor.com"}],"readme":"# agentailor-mcp\n\nAn MCP server that connects your AI assistant to [Agentailor](https://agentailor.com) — search the blog, read articles in full, and pull docs from the open-source repos, all over the Model Context Protocol.\n\nUse it with no clone required:\n\n- **npx (local stdio)** — run `npx @agentailor/mcp` as a command in Claude Desktop and other local clients.\n- **Hosted HTTP** _(coming soon)_ — a zero-install Agentailor-hosted endpoint you point your client at.\n\nScaffolded with [`@agentailor/create-mcp-server`](https://www.npmjs.com/package/@agentailor/create-mcp-server) on [FastMCP](https://github.com/punkpeye/fastmcp) — the tool building its own ecosystem.\n\n## Tools\n\n| Tool                         | What it does                                                                                                                 |\n| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |\n| `agentailor_get_blog_index`  | Returns the blog's content map (Markdown) — every published article with title, date, tags, summary.                         |\n| `agentailor_search_articles` | Ranked article search in one tool: free-text `query`, `tags` filter, `guidesOnly`, `limit`, `response_format`. Returns JSON. |\n| `agentailor_read_article`    | Fetches a single article's full Markdown by its `blog.agentailor.com` `.md` URL.                                             |\n| `agentailor_list_repos`      | Lists the public repos in the `agentailor` GitHub org. Returns JSON.                                                         |\n| `agentailor_read_repo_doc`   | Reads a `README.md` or `docs/*.md` from a given org repo (Markdown).                                                         |\n\nScope is Agentailor's public content: the blog and the open-source org repos. The list/search tools (`search_articles`, `list_repos`) return structured JSON; the content tools return raw Markdown.\n\n## Use it\n\n### npx (local stdio)\n\nRun the server as a local command — ideal for Claude Desktop. In `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"agentailor\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@agentailor/mcp\"]\n    }\n  }\n}\n```\n\nThe repo tools read **public** GitHub data, so no token is required. If you hit GitHub's unauthenticated rate limit (60 requests/hour), pass a token to raise it to 5,000/hour:\n\n```json\n{\n  \"mcpServers\": {\n    \"agentailor\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@agentailor/mcp\"],\n      \"env\": { \"GITHUB_TOKEN\": \"ghp_your_token\" }\n    }\n  }\n}\n```\n\n### Hosted HTTP (coming soon)\n\nA zero-install, Agentailor-hosted HTTP endpoint is planned — point any streamable-HTTP MCP client at a single URL, nothing to install or run. It isn't live yet; for now use the npx setup above. The endpoint URL will be published on [agentailor.com](https://agentailor.com) when it's ready.\n\n## Designed to the \"Writing Effective Tools for AI Agents\" playbook\n\nThese tools follow the five principles from Agentailor's [Writing Effective Tools for AI Agents](https://blog.agentailor.com/posts/writing-tools-for-ai-agents) — here's exactly how:\n\n| Principle                                | How this server applies it                                                                                                                                                           |\n| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| **1. Strategic selection**               | One `agentailor_search_articles` covers discovery by topic, by tag, and guides-only — instead of four fragmented search tools. Tools map to how you actually work, not to endpoints. |\n| **2. Clear namespacing**                 | Every tool is prefixed `agentailor_`, so it never collides with other MCP servers on your client.                                                                                    |\n| **3. Meaningful context**                | Read tools take `response_format: \"concise\" \\| \"detailed\"`. Results carry titles, tags, and summaries you can reason on — not bare IDs.                                              |\n| **4. Token efficiency + guiding errors** | Search defaults to 20 results with an overflow hint that tells the agent how to narrow. A GitHub rate-limit returns \"set a `GITHUB_TOKEN`\" guidance, not a raw 403.                  |\n| **5. Descriptions as prompts**           | Each tool description includes a **When to use** section with example calls, and every parameter documents its shape with an example.                                                |\n\n## Deploy your own HTTP instance\n\nThe HTTP transport serves the MCP endpoint at `POST /mcp` and a `GET /health` check.\n\n### Native Node host\n\nOn any platform that runs a Node web service from this repo:\n\n- **Build command:** `pnpm install --frozen-lockfile && pnpm build`\n- **Start command:** `pnpm start:http`\n- **Health check path:** `/health`\n- **Environment:**\n  - `GITHUB_TOKEN` — a token with public read access (recommended on a shared/hosted instance; raises the GitHub limit to 5,000/hour).\n  - `PORT` — most hosts inject this automatically; the server reads it. Defaults to `3000` if unset.\n\nNode 20 is pinned via `engines` and `.node-version`.\n\n### Docker\n\nA `Dockerfile` is included for running the server on any container host. The `TRANSPORT` build arg selects the entrypoint:\n\n```bash\ndocker build --build-arg TRANSPORT=http -t agentailor-mcp-http .\ndocker run -p 3000:3000 -e GITHUB_TOKEN=ghp_your_token agentailor-mcp-http\n```\n\nConnect any HTTP MCP client to `http://<host>:3000/mcp`.\n\n## Configuration\n\n| Variable        | Required | Purpose                                                                                                                                                  |\n| --------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `PORT`          | No       | HTTP transport port (default `3000`). Injected by most hosts. Ignored by stdio.                                                                          |\n| `GITHUB_TOKEN`  | No       | Raises the GitHub API limit for the repo tools from 60/hr to 5,000/hr. Any token with public read access works. Recommended on a hosted/shared instance. |\n| `BLOG_BASE_URL` | No       | Override the blog origin (for local/staging testing).                                                                                                    |\n\nNo credentials are required to run — all exposed data is public.\n\n## Develop locally (contributors)\n\nClone and run from source:\n\n```bash\npnpm install\npnpm build\n\n# stdio (local clients)\npnpm start:stdio\n\n# HTTP on PORT (default 3000)\npnpm start:http\n```\n\nDev mode with reload: `pnpm dev:stdio` or `pnpm dev:http`.\n\n```bash\npnpm test          # Vitest unit tests\npnpm typecheck     # tsc --noEmit\npnpm format:check  # Prettier check\npnpm inspect       # MCP Inspector against the HTTP server\npnpm inspect:stdio # list tools over stdio\n```\n\n## Releasing\n\nThe npm package publishes via GitHub Actions when a **GitHub Release** is published:\n\n1. Bump `version` in `package.json` (and `src/server.ts`), commit.\n2. Cut a GitHub Release / tag.\n3. The `publish` workflow runs the test/build gates and publishes `@agentailor/mcp` to npm (auth via the `NPM_TOKEN` repo secret).\n\n## Learn more\n\n- [Writing Effective Tools for AI Agents](https://blog.agentailor.com/posts/writing-tools-for-ai-agents) — the design playbook this server follows\n- [`@agentailor/create-mcp-server`](https://github.com/agentailor/create-mcp-server) — the scaffolder\n- [FastMCP](https://github.com/punkpeye/fastmcp) · [Model Context Protocol](https://modelcontextprotocol.io/)\n\n## License\n\n[Apache 2.0](LICENSE) © Agentailor\n","readmeFilename":"README.md"}