ESA MCP Server

ESA MCP 服务

这是一个用于与 esa.io API 集成的 Model Context Protocol (MCP) 服务。 使用 Deno 和 JSR 发布。

功能

目前，提供以下基本的 esa.io API 操作作为 MCP 工具：

• 获取用户信息
• 获取文章列表
• 获取文章详情
• 创建文章
• 更新文章
• 删除文章

使用方法（通过 JSR 运行）

由于已发布到 JSR (JavaScript Registry)，无需在本地克隆仓库，即可直接运行 MCP 服务。

前提条件

• 已安装 Deno v2.0 或更高版本。
• 网络连接。

设置

1. 设置环境变量： 在要运行服务的目录（通常是项目工作区根目录）中创建 .env 文件，并写入以下内容：

   # .env
   ESA_TEAM_NAME="YOUR_ESA_TEAM_NAME" # Replace with your esa.io team name
   ESA_TOKEN="YOUR_ESA_API_TOKEN"     # Replace with your esa.io API access token
   

   将 YOUR_ESA_TEAM_NAME 和 YOUR_ESA_API_TOKEN 替换为实际值。

   如何创建 esa.io API 令牌：

   • 访问你的 esa.io 团队页面（例如：https://<your-team-name>.esa.io/）。
   • 点击右上角的个人图标，选择“设置 (Settings)”>“应用程序”。
   • 在“个人访问令牌 (Personal access tokens)”部分，点击“生成新令牌 (Generate new token)”。
   • 输入令牌名称（例如：mcp-server），并选择所需的权限范围。此 MCP 服务至少需要以下权限：
     • read（读取文章）
     • write（创建、更新和删除文章）
     • read_user（获取用户信息）
   • 点击“生成令牌 (Generate token)”。
   • 请务必复制显示的令牌并妥善保存。该令牌仅显示一次。
   • 将复制的令牌粘贴为上述 .env 文件中的 ESA_TOKEN 值。

运行

运行以下命令：

# 最新版を使う場合 (推奨)
deno run --allow-env --allow-net=api.esa.io --allow-read jsr:@masseater/esa-mcp-server

# 特定バージョン (例: 0.1.0) を使う場合
# deno run --allow-env --allow-net=api.esa.io --allow-read jsr:@masseater/[email protected]

• --allow-env：允许访问环境变量。（由于依赖库 (npm:debug) 会在内部尝试读取所有环境变量，因此仅允许特定变量 (ESA_TOKEN, ESA_TEAM_NAME) 的 --allow-env=... 会导致错误。）
• --allow-net=api.esa.io：仅允许访问所需的 esa.io API (api.esa.io) 网络。
• --allow-read：允许读取 Deno 内部使用的 npm 包等缓存，以及（如有使用）.env 文件。
  • **注：**原则上应将访问权限限制在最小范围内，但 Deno 缓存目录的位置因环境而异，因此难以限制为特定路径。因此，为了方便起见，这里使用了 --allow-read。请注意，这会允许广泛读取文件系统。首次运行等情况下，可能会显示提示，要求允许访问 Deno 缓存目录等位置。
• jsr:@masseater/esa-mcp-server：指定要运行的 JSR 包。省略版本时，将始终使用最新版本（推荐）。如果要使用特定版本，可以添加 @<版本>（例如 @0.1.0）或版本范围（例如 @^0.1.0）。

成功启动后，标准输出中会重复显示如下 JSON-RPC ping 消息。这表示服务正在等待客户端连接。按 Ctrl+C 退出。

{\"method\":\"ping\",\"jsonrpc\":\"2.0\",\"id\":0}
{\"method\":\"ping\",\"jsonrpc\":\"2.0\",\"id\":1}
{\"method\":\"ping\",\"jsonrpc\":\"2.0\",\"id\":2}
...

配置为 MCP 服务（在 Cursor 中使用）

若要在 Cursor 中将其用作 MCP 服务，请在 .cursor/mcp.json 中进行如下配置。

🚨 警告：如以下配置示例所示，直接写入 API 令牌等信息会带来安全风险。如果 .cursor 目录未被 .gitignore 忽略，提交此文件会导致机密信息泄露。强烈建议尽可能使用 .env 文件，并通过 ${env:VAR_NAME} 格式读取。如果直接写入，请绝对不要提交 .cursor/mcp.json 文件！ 🚨

{
  "mcpServers": {
    "esa-mcp-server-jsr": {
      "command": "deno",
      "args": [
        "run",
        "--allow-env",
        "--allow-net=api.esa.io",
        "--allow-read",
        "jsr:@masseater/esa-mcp-server"
      ],
      "env": {
        "ESA_TOKEN": "YOUR_ACTUAL_ESA_API_TOKEN",
        "ESA_TEAM_NAME": "YOUR_ACTUAL_ESA_TEAM_NAME"
      }
    }
  }
}

• 要点：
  • command：指定 deno。
  • args：指定 run、所需权限 (--allow-env, --allow-net=api.esa.io, --allow-read) 以及 JSR 包的 specifier。（由于依赖库的原因，需要使用 --allow-env。）
  • env：直接设置环境变量。使用此方法时，绝对不要提交 .cursor/mcp.json。

---

开发（本地）

如果要参与此 MCP 服务的开发，或在本地修改、运行代码，请按照以下步骤操作。

前提条件

• 已安装 Deno v2.0 或更高版本。
• 已安装 Git。
• 拥有 esa.io API 令牌。

设置 (Setup)

1. 克隆仓库 (Clone the repository)：

   git clone https://github.com/masseater/esa-mcp-server.git
   cd esa-mcp-server
   

2. 设置环境变量 (Set up environment variables)： 复制 .env.example 并创建 .env 文件，填写你的 esa.io API 令牌和团队名称。

   cp .env.example .env
   # Edit .env with your actual token and team name
   

3. （推荐）启用 Git 钩子 (Enable Git Hooks (Recommended))： 为了在提交前自动检查代码，请运行以下命令来设置 Git 钩子。

   deno run -A https://deno.land/x/deno_hooks/mod.ts install
   

本地运行 (Running Locally)

deno run --allow-env --allow-net --allow-read main.ts

或者，启用热重载后运行：

deno task dev

检查和测试 (Checks and Tests)

你可以使用以下命令一次性运行格式化、lint、类型检查和单元测试。pre-commit 钩子也会在提交前自动运行这些检查。

deno task check:all

集成测试（与实际 esa.io API 通信的测试）需要单独运行。.env 文件必须正确配置。

deno task test:integration

发布到 JSR (Publishing to JSR)

按照以下步骤将新版本发布到 JSR。

1. 更新 deno.jsonc 中的 version 字段。
2. 提交更改。
3. 运行发布前检查。

   deno publish --dry-run
   

4. 如果没有问题，则发布。

   deno publish
   

许可证 (License)

本项目根据 MIT License 发布。 （注意：如果仓库中还没有 LICENSE 文件，则需要另行添加。）

其他 (Misc)

生成者 (Generated by)

由 Cursor (gemini-2.5-pro-exp-03-25) 生成