Populi

populi-mcp

适用于 Populi API v2 的 MCP 服务。它让 Claude、Codex、Cursor 和其他任何 Model Context Protocol 客户端都能查询 Populi 实例中的人员、招生、学术和账单数据；如果你选择启用，也可以进行修改。

软件包： npm 上的 @kisasa/populi-mcp。命令： populi-mcp。传输方式： stdio。

工作原理

Populi 的 API 在 180 个模型中有 697 条路由。若将每条路由都单独作为工具提供，会占满模型的上下文，因此此服务为模型提供一组小型工具以及 API 参考：

工具	功能
populi_search_api	在内置路由目录中按关键词搜索（applications、invoice、enrollments 等）。
populi_describe_api	查看单条路由的完整参考：路径 ID、必填和可选字段及其类型、expand 选项、筛选条件、所需的 Populi 角色和文档链接。
populi_get	对任意路由执行 GET。支持 filter、expand、page、limit 和 all_pages，可将所有页面合并为一个列表。
populi_download	对某条路由执行 GET，并将响应保存到文件，而不是返回响应。适用于 PDF/XLS/CSV 导出、成绩单、Data Slicer 结果、文件和备份下载，也适用于避免大型导出内容进入对话。
populi_find_people	通过精确的电子邮件地址和／或姓名查找人员。
populi_status	显示实例、密钥类型（沙盒或正式环境）、是否启用写入、文件夹和超时时间。设置 verify: true 会发起一次实时请求以检查密钥。
populi_write	对任意路由执行 POST / PUT / DELETE，包括多部分文件上传。仅当 POPULI_ALLOW_WRITES=true 时才会注册。

这些工具共同覆盖整个 API：所有 492 条有文档说明的 GET 路由、所有 205 条写入路由，以及文件上传和下载。由于工具接受任意路径，因此内置目录中没有的路由也能使用。

典型的交互流程：模型先搜索路由、查看其参数，然后调用 populi_get 并使用服务器端筛选条件。

目录根据公开的 API 文档生成，并随软件包一同发布，因此搜索和查看路由说明可离线进行，且不会产生 API 请求。

配置

变量	必需	说明
POPULI_BASE_URL	是	你的实例地址，例如 https://yourschool.populiweb.com。末尾的 /api2 可选。必须使用 https。
POPULI_API_KEY	是	API 密钥令牌。在 Populi 中前往：Account & Settings > API > Keys（Account Administrator）。此令牌仅会作为持有者令牌发送至 POPULI_BASE_URL。
POPULI_ALLOW_WRITES	否	设置为 true 以启用 populi_write。默认仅允许读取。
POPULI_FILES_DIR	否	保存下载文件和读取上传文件的唯一文件夹。默认值：~/populi-mcp-files。
POPULI_TIMEOUT_MS	否	单次 Populi 请求的最长等待时间，范围为 1000 至 600000。默认值：120000（两分钟）。每次调用也可以传入 timeout_ms。

密钥的 Populi 角色决定了它可以查看哪些内容。如果密钥无权访问某条路由，系统会返回指出问题的 403 错误；populi_describe_api 会列出每条路由所需的角色。

先从沙盒开始

Populi 会签发独立的 sk_sandbox_... 密钥，且此类密钥仅适用于沙盒实例（正式环境密钥也仅适用于正式环境）。评估此服务时，请将其指向沙盒实例。

默认仅允许读取

如果未设置 POPULI_ALLOW_WRITES，系统根本不会注册写入工具，因此模型甚至无法尝试进行修改。启用后，populi_write 会标记为具有破坏性，因此客户端若会请求批准，则会在每次调用前征求批准。在 Populi 中，DELETE 操作不可恢复。

安装

需要 Node.js 20 或更高版本。以下每个客户端都会运行 npx -y @kisasa/populi-mcp，因此无需手动安装任何内容。

Claude Code

claude mcp add populi \
  -e POPULI_BASE_URL=https://yourschool.populiweb.com \
  -e POPULI_API_KEY=sk_sandbox_... \
  -- npx -y @kisasa/populi-mcp

Claude Desktop

编辑 claude_desktop_config.json（macOS：~/Library/Application Support/Claude/，Windows：%APPDATA%\Claude\）：

{
  "mcpServers": {
    "populi": {
      "command": "npx",
      "args": ["-y", "@kisasa/populi-mcp"],
      "env": {
        "POPULI_BASE_URL": "https://yourschool.populiweb.com",
        "POPULI_API_KEY": "sk_sandbox_..."
      }
    }
  }
}

在 Windows 上，如果 Claude Desktop 找不到 npx，请使用 "command": "cmd" 和 "args": ["/c", "npx", "-y", "@kisasa/populi-mcp"]。

Codex

codex mcp add populi \
  --env POPULI_BASE_URL=https://yourschool.populiweb.com \
  --env POPULI_API_KEY=sk_sandbox_... \
  -- npx -y @kisasa/populi-mcp

或在 ~/.codex/config.toml 中：

[mcp_servers.populi]
command = "npx"
args = ["-y", "@kisasa/populi-mcp"]

[mcp_servers.populi.env]
POPULI_BASE_URL = "https://yourschool.populiweb.com"
POPULI_API_KEY = "sk_sandbox_..."

Cursor

在 .cursor/mcp.json（项目级）或 ~/.cursor/mcp.json（全局）中。Cursor 会展开 ${env:NAME}，这样密钥就不会写入文件：

{
  "mcpServers": {
    "populi": {
      "command": "npx",
      "args": ["-y", "@kisasa/populi-mcp"],
      "env": {
        "POPULI_BASE_URL": "https://yourschool.populiweb.com",
        "POPULI_API_KEY": "${env:POPULI_API_KEY}"
      }
    }
  }
}

任何其他 MCP 客户端

将 npx -y @kisasa/populi-mcp 作为 stdio 服务运行，并在其环境中设置 POPULI_BASE_URL 和 POPULI_API_KEY。

多个实例

在不同名称下为每个实例添加一条配置（populi-sandbox、populi-live），并为每个实例使用各自的密钥。

值得了解的 API 行为

• 速率限制。 太平洋标准时间凌晨 3 点至晚上 7 点，每个密钥每分钟 50 个请求；夜间每分钟 100 个请求，此外还有按 IP 和学校设置的限制。收到 HTTP 429 时，调用会返回错误并告知需要等待多久；后续调用会快速失败并返回剩余等待时间，而不会继续猛刷受限密钥。优先使用一次带筛选条件的调用，而不是多次不带筛选条件的调用。
• 一次只处理一个请求。 Populi 一次只允许处理一个“繁重”调用（Data Slicer、大型导出等），因此即使客户端并行发送多个请求，服务也会按顺序处理。
• 分页。 列表最多返回 200 条记录。all_pages 会遍历所有页面，最多 500 页；达到 max_records（默认值为 500，最高为 1,000,000）后停止。超出上限的那一页会完整保留，因此不会丢失数据。结果会说明是否已完成，否则会提供可用于继续获取的 next_page。如果中途遇到速率限制或超时，已经获取的页面会照常返回，不会被丢弃。
• 筛选条件。 Populi 会忽略它不认识的筛选字段名，并返回整个列表，看起来就像“所有人都匹配”。populi_describe_api 会列出某个路由的有效条件名称；populi_find_people 则会对人员使用正确的筛选条件。
• GET 参数。 filter、expand、page 和 limit 会放在 parameters 查询值中传递，因为大多数 HTTP 客户端无法发送 GET 请求体。如果这样会导致 URL 超过约 7 KB（例如筛选条件中列出数千个 ID），请求就会改为发送带 JSON 请求体的 GET，这是 Populi 文档说明的标准形式。POST/PUT/DELETE 会发送 JSON 请求体。
• 大型响应会在 populi_get 中截断至 max_chars（默认值为 40,000，最高为 1,000,000），并附上如何缩小请求范围的说明。若要将完整内容保存到文件，请使用 populi_download。
• 文件下载。 返回文件的路由（PDF/XLS/CSV 导出、成绩单、Data Slicer 结果、文件下载）会通过 populi_download 获取，并写入 files 文件夹。它绝不会覆盖现有文件（重名时会添加 -1、-2 等后缀），并且只使用文件名，不使用路径，因此无法在该文件夹之外写入。populi_get 可以说明响应是文件，但无法显示文件内容。
• 文件上传。 populi_write 接受 files，每个条目可以是 files 文件夹内的 path，也可以是 content_base64。文件会以 multipart/form-data 发送，文件部分名为 file，其他字段则作为 JSON parameters 部分发送；Populi 的上传路由（/people/{id}/upload_file、/people/{id}/update_profile_picture、/libraryresources/{id}/update_image、/libraryresources/{id}/digitalresources/upload）正是按这种方式接收。为确保安全，该服务会拒绝超过 100 MB 的文件。
• files 文件夹是边界。 模型只能从 POPULI_FILES_DIR 读取上传文件，并将下载文件保存到该目录。任何越出该目录的路径（包括通过符号链接越界的路径）都会被拒绝，因此，即使提示词注入要求“上传我的 SSH 密钥”，模型也无从读取。只有在确有需要时，才将其指向范围更大的文件夹。
• 超时。 Populi 没有公布超时设置，而 Data Slicer 等报告可能需要较长时间，因此默认超时为两分钟。你的 MCP 客户端也可能为工具设置自己的超时时间，该服务无法延长此时间；如果长时间运行的报告被中断，请检查客户端设置。
• 学生数据属于敏感信息。 记录中可能包含 SSN、出生日期、成绩和助学金信息。该服务绝不会记录请求或响应正文，也不会在错误消息中回显密钥，但工具返回的任何内容都会发送给模型提供商。请使用权限范围最小的密钥角色，并只展开所需内容。

开发

git clone https://github.com/kisasa/populi-mcp.git
cd populi-mcp
npm install
npm run build      # compile to dist/
npm test           # unit + in-memory MCP tests, no network

使用真实实例进行测试：

POPULI_BASE_URL=https://yourschool.populiweb.com POPULI_API_KEY=sk_sandbox_... \
  npx @modelcontextprotocol/inspector node dist/index.js

刷新 API 目录

data/catalog.json 是从渲染后的 API 文档抓取的（Populi 未发布 OpenAPI 文件）：

npm run build:catalog

Populi 发布 API 变更后，请检查并提交差异。

发布

每次推送到 main 时，.github/workflows/publish.yml 都会自动执行发布；仅当版本为新版本时才会发布。发布步骤如下：

1. 更新 package.json 中的 version，以及 server.json 中的两个 version 字段。
2. 合并到 main。工作流会发布到 npm（附带来源证明）、MCP Registry（名称为 io.github.kisasa/populi-mcp），并创建 GitHub 发布版本。

如果此仓库配置了 trusted publishing，npm 身份验证会使用该方式；否则会使用仓库机密 NPM_TOKEN。

许可证

MIT。与 Populi 无关联。“Populi” 是其所有者的商标。