内容
# agentailor-mcp
一个连接您的AI助手至 [Agentailor](https://agentailor.com) 的MCP服务器 - 搜索博客，阅读文章，提取开源仓库的文档，均通过模型上下文协议。
无需克隆即可使用：
- **npx（本地stdio）** - 在Claude Desktop和其他本地客户端中运行 `npx @agentailor/mcp` 作为命令。
- **托管HTTP** _（即将推出）_ - 一个零安装的Agentailor托管端点，您可以将客户端指向该端点。
使用 [`@agentailor/create-mcp-server`](https://www.npmjs.com/package/@agentailor/create-mcp-server) 在 [FastMCP](https://github.com/punkpeye/fastmcp) 上构建 - 构建自己的生态系统。
## 工具
| 工具 | 功能 |
| --- | --- |
| `agentailor_get_blog_index` | 返回博客的内容地图（Markdown）- 每个已发布的文章，包含标题，日期，标签，摘要。 |
| `agentailor_search_articles` | 排名文章搜索 - 一个工具中包含自由文本查询，标签筛选，指南筛选，限制，结果格式。返回JSON。 |
| `agentailor_read_article` | 通过其 `blog.agentailor.com` `.md` URL获取单个文章的完整Markdown。 |
| `agentailor_list_repos` | 列出 `agentailor` GitHub组织的公共仓库。返回JSON。 |
| `agentailor_read_repo_doc` | 从给定的组织仓库中读取 `README.md` 或 `docs/*.md` （Markdown）。 |
范围是Agentailor的公共内容：博客和开源组织仓库。列表/搜索工具（`search_articles`，`list_repos`）返回结构化JSON；内容工具返回原始Markdown。
## 使用
### 连接您的客户端（通过npx进行本地stdio）
服务器作为本地stdio命令运行 - `npx -y @agentailor/mcp` - 因此任何MCP客户端都可以启动它。在下面为您的客户端添加配置。无需安装步骤；`npx`会在首次运行时获取包。
<details open>
<summary><strong>Claude Desktop</strong></summary>
在 `claude_desktop_config.json` 中（设置 › 开发者 › 编辑配置），然后重启Claude Desktop：
```json
{
"mcpServers": {
"agentailor": {
"command": "npx",
"args": ["-y", "@agentailor/mcp"]
}
}
}
```
</details>
<details>
<summary><strong>Cursor</strong></summary>
与Claude相同的架构。 在您的项目中创建 `.cursor/mcp.json` （或 `~/.cursor/mcp.json` 以适用于所有项目）：
```json
{
"mcpServers": {
"agentailor": {
"command": "npx",
"args": ["-y", "@agentailor/mcp"]
}
}
}
```
</details>
<details>
<summary><strong>VS Code / GitHub Copilot</strong></summary>
在您的工作区中创建 `.vscode/mcp.json`。请注意顶级键是 `servers` （而不是 `mcpServers`）：
```json
{
"servers": {
"agentailor": {
"command": "npx",
"args": ["-y", "@agentailor/mcp"]
}
}
}
```
</details>
<details>
<summary><strong>OpenAI Codex</strong></summary>
添加到 `~/.codex/config.toml`：
```toml
[mcp_servers.agentailor]
command = "npx"
args = ["-y", "@agentailor/mcp"]
```
或使用CLI：`codex mcp add agentailor -- npx -y @agentailor/mcp`。
</details>
<details>
<summary><strong>任何其他MCP客户端</strong></summary>
使用以下命令将其作为stdio服务器运行：
```
npx -y @agentailor/mcp
```
</details>
#### 提高GitHub速率限制（可选）
仓库工具读取 **公共** GitHub数据，因此不需要令牌。 如果您遇到GitHub的未经身份验证的速率限制（60个请求/小时），请设置一个 `GITHUB_TOKEN` （任何具有公共读取访问权限的令牌）以将其提高到5,000个请求/小时。 在JSON配置中，为服务器条目添加一个 `env` 块：
```json
{
"mcpServers": {
"agentailor": {
"command": "npx",
"args": ["-y", "@agentailor/mcp"],
"env": { "GITHUB_TOKEN": "ghp_your_token" }
}
}
}
```
对于Codex，请在 `config.toml` 中将其添加到服务器的 `env` 下；对于VS Code，请在 `servers` 条目下添加。
### 托管HTTP（即将推出）
计划提供一个零安装、Agentailor托管的HTTP端点 - 指向任何可流式传输的HTTP MCP客户端到单个URL，无需安装或运行。 它尚未上线；现在请使用上面的npx设置。 端点URL将在准备就绪时在 [agentailor.com](https://agentailor.com) 上发布。
## 设计遵循“为AI代理编写有效工具”的手册
这些工具遵循Agentailor的 [为AI代理编写有效工具](https://blog.agentailor.com/posts/writing-tools-for-ai-agents) 中的五项原则 - 这里是具体实现方式：
| 原则 | 服务器应用方式 |
| --- | --- |
| **1. 策略选择** | 一个 `agentailor_search_articles` 涵盖了按主题、标签和仅指南的发现 - 而不是四个分散的搜索工具。 工具映射到您实际的工作方式，而不是端点。 |
| **2. 清晰的命名空间** | 每个工具都以 `agentailor_` 为前缀，因此它永远不会与客户端上的其他MCP服务器冲突。 |
| **3. 有意义的上下文** | 读取工具采用 `response_format: "concise" \| "detailed"`。 结果包含标题、标签和摘要，您可以对其进行推理 - 而不是裸ID。 |
| **4. Token效率 + 引导错误** | 搜索默认返回20个结果，并带有溢出提示，告诉代理如何缩小范围。 GitHub速率限制返回“设置 `GITHUB_TOKEN`”指导，而不是原始403。 |
| **5. 描述为提示** | 每个工具描述都包含一个 **何时使用** 部分，包含示例调用，并且每个参数都用示例记录其形状。 |
## 部署您自己的HTTP实例
HTTP传输在 `POST /mcp` 和 `GET /health` 检查处提供MCP端点。
### 原生Node主机
在任何平台上运行Node Web服务：
- **构建命令：** `pnpm install --frozen-lockfile && pnpm build`
- **启动命令：** `pnpm start:http`
- **健康检查路径：** `/health`
- **环境：**
- `GITHUB_TOKEN` - 具有公共读取访问权限的令牌（在共享/托管实例上推荐；将GitHub限制提高到5,000/小时）。
- `PORT` - 大多数主机自动注入；服务器读取。 如果未设置，则默认为 `3000`。
Node 20通过 `engines` 和 `.node-version` 固定。
### Docker
包含一个 `Dockerfile` 以在任何容器主机上运行服务器。 `TRANSPORT` 构建参数选择入口点：
```bash
docker build --build-arg TRANSPORT=http -t agentailor-mcp-http .
docker run -p 3000:3000 -e GITHUB_TOKEN=ghp_your_token agentailor-mcp-http
```
将任何HTTP MCP客户端连接到 `http://<host>:3000/mcp`。
## 配置
| 变量 | 必需 | 目的 |
| --- | --- | --- |
| `PORT` | 否 | HTTP传输端口（默认 `3000`）。 大多数主机注入；stdio忽略。 |
| `GITHUB_TOKEN` | 否 | 将仓库工具的GitHub API限制从60/小时提高到5,000/小时。 任何具有公共读取访问权限的令牌都有效。 在托管/共享实例上推荐。 |
| `BLOG_BASE_URL` | 否 | 覆盖博客源（用于本地/测试）。 |
运行无需凭证 - 所有公开数据均为公共。
## 本地开发（贡献者）
克隆并从源代码运行：
```bash
pnpm install
pnpm build
# stdio（本地客户端）
pnpm start:stdio
# HTTP在PORT（默认为3000）
pnpm start:http
```
开发模式，自动重新加载： `pnpm dev:stdio` 或 `pnpm dev:http`。
```bash
pnpm test # Vitest单元测试
pnpm typecheck # tsc --noEmit
pnpm format:check # Prettier检查
pnpm inspect # MCP Inspector针对HTTP服务器
pnpm inspect:stdio # 在stdio上列出工具
```
## 发布
npm包通过GitHub Actions发布，当发布 **GitHub Release** 时：
1. 在 `package.json` （和 `src/server.ts`）中增加 `version` ，提交。
2. 切割GitHub Release / 标签。
3. `publish` 工作流运行测试/构建门控并将 `@agentailor/mcp` 发布到npm（通过 `NPM_TOKEN` 仓库秘密授权）。
## 了解更多
- [为AI代理编写有效的工具](https://blog.agentailor.com/posts/writing-tools-for-ai-agents) - 此服务器遵循的设计手册
- [`@agentailor/create-mcp-server`](https://github.com/agentailor/create-mcp-server) - 构建工具
- [FastMCP](https://github.com/punkpeye/fastmcp) · [模型上下文协议](https://modelcontextprotocol.io/)
## 许可证
[Apache 2.0](LICENSE) © Agentailor
