ESA MCP 服务器

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

功能

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

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

使い方 (从 JSR 运行)

由于它已发布到 JSR (JavaScript Registry)，因此您可以直接运行 MCP 服务器，而无需在本地克隆存储库。

前提条件 (Prerequisites)

• 已安装 Deno v2.0 或更高版本。(Deno v2.0 or later installed.)
• 互联网连接。(Internet connection.)

设置 (Setup)

1. 设置环境变量 (Set up environment variables): 在您要运行服务器的目录（通常是项目工作区根目录）中创建一个 .env 文件，并添加以下内容:(Create a .env file in the directory where you want to run the server (usually the project workspace root) and add the following content:)

   # .env
   ESA_TEAM_NAME="YOUR_ESA_TEAM_NAME" # 替换为您的 esa.io 团队名称
   ESA_TOKEN="YOUR_ESA_API_TOKEN"     # 替换为您的 esa.io API 访问令牌
   

   请将 YOUR_ESA_TEAM_NAME 和 YOUR_ESA_API_TOKEN 替换为您的实际值。(Replace YOUR_ESA_TEAM_NAME and YOUR_ESA_API_TOKEN with your actual values.)

   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 的值。

运行 (Running)

运行以下命令:(Run the following command:)

# 使用最新版本 (推荐)
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/esa-mcp-server@0.1.0

• --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 中使用 (Usage as MCP Server in 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。

---

开发 (本地) (Local Development)

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

前提条件 (Prerequisites)

• 已安装 Deno v2.0 或更高版本。(Deno v2.0 or later installed.)
• 已安装 Git。(Git installed.)
• 拥有 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)

generated by Cursor (gemini-2.5-pro-exp-03-25)