kompa-mcp-server

MCP（Model Context Protocol）服务器，将 Kompa 社交聆听数据——buzzes、情感分布、趋势线、热门话题、唯一作者——作为工具暴露给任何 MCP 客户端调用。它的设计目的是让你可以直接在 Claude（Desktop 或 Code）中讨论 Kompa 数据，而不是使用独立的聊天界面。

该包独立于 kompa-chat Next.js 应用——它只复用了相同的 Kompa GraphQL API 和登录流程，移植到一个纯 MCP 服务器中。它提供两个入口点：

• build/index.js — stdio 传输，适用于通过本地配置生成子进程的本地 MCP 客户端（Claude Desktop/Code）。

• build/http.js — Streamable HTTP 传输，多租户：一个托管的连接器 URL 可以为多个客户提供服务。完整的 VPS 部署指南（systemd + Caddy + 客户接入）请参阅 DEPLOY.md。

账户与主题配置

没有单独的 API-key 系统。每个客户已经有 Kompa 用户名/密码——在这里也使用同样的凭据，通过一次工具调用来完成：

configure_account({ username, password, topicIds: ["topic-id-1", ...] })

在对话开始时调用一次（一旦你提到你的凭据/主题，Claude 会自动执行此操作，或者你也可以明确要求它这样做）。之后所有其他工具都会复用该账户和 topic_ids，直到你再次调用 configure_account——无需在每次调用时重复提供，不过你仍然可以在每次调用时传入 topicIds 来覆盖。

之所以采用这种方式而不是基于 header 的认证，是因为 Claude 针对连接器的自定义请求头目前仍处于受限的 beta 发布阶段——请参阅 DEPLOY.md 中的“Auth model”说明。

对于 stdio 入口点，你可以通过设置 KOMPA_USERNAME/KOMPA_PASSWORD/KOMPA_DEFAULT_INDEXES 环境变量来完全跳过工具调用——在这种情况下，账户会在启动时预先配置好。

工具

所有数据工具都接受 fromDate/toDate（"YYYY-MM-DD HH:mm:ss"）、可选的 types、query、sentiments，以及可选的 topicIds（未提供时回退到通过 configure_account 设置的 topicIds）。

安装

npm install
npm run build

复制 .env.example 作为参考（仅与 stdio 入口点相关——见上文）。

独立使用（发布之前）

将任何 MCP 客户端直接指向构建好的入口文件：

{
  "mcpServers": {
    "kompa": {
      "command": "node",
      "args": ["/absolute/path/to/kompa-mcp-server/build/index.js"]
    }
  }
}

• Claude Desktop：将此配置块放入 claude_desktop_config.json（Settings → Developer → Edit Config）。

• Claude Code：将相同的 mcpServers 配置块放在项目根目录的 .mcp.json 中，或者运行：

claude mcp add kompa -- node /absolute/path/to/kompa-mcp-server/build/index.js

编辑配置后重启客户端，然后在聊天中说出类似 “我的 Kompa 账户是 X/Y，主题 ID 是 Z——查询 'foo' 在 2026-08-01 到 2026-08-21 之间的情感分布是怎样的？” 这样的话——Claude 会先调用 configure_account，再调用数据工具。

发布到 npm

这样用户就可以通过 npx kompa-mcp-server 安装，而不是使用本地路径：

npm login
npm publish --access public

然后 MCP 配置变为：

{
  "mcpServers": {
    "kompa": {
      "command": "npx",
      "args": ["-y", "kompa-mcp-server"]
    }
  }
}

发布到 Claude Code 插件市场

Claude Code 以及（对于 Team/Enterprise 组织）claude.ai 本身都可以直接从 git 仓库添加插件市场——这里不需要发布 npm 包，因为 marketplace-example/plugins/kompa-mcp/.claude-plugin/plugin.json 指向的是你托管的 HTTP 连接器（参见 DEPLOY.md），而不是本地包。目录结构：

marketplace-example/
├── .claude-plugin/
│   └── marketplace.json
└── plugins/
    └── kompa-mcp/
        └── .claude-plugin/
            └── plugin.json      # edit the connector URL in here first

作为维护者：

1. 将 marketplace-example/plugins/kompa-mcp/.claude-plugin/plugin.json 中的 url 修改为你实际部署的域名（https://mcp.yourdomain.com/mcp）。

2. 将包含 marketplace-example/ 目录结构的仓库（将该文件夹重命名为你想要的任何仓库根目录名称）推送到 GitHub——公开，或者如果只有你的组织需要则设为私有（私有仓库要求所有安装者通过其 GitHub/git 凭据拥有仓库访问权限）。

3. 分享仓库 URL。

作为安装它的 Claude Code 用户：

/plugin marketplace add https://github.com/<you>/<marketplace-repo>
/plugin install kompa-mcp-plugin@<marketplace-name>

作为 claude.ai Team/Enterprise 组织（无 CLI，仅 GUI）：

1. 组织所有者：Organization settings → Connectors/Plugins → Add plugin marketplace → “Add from a repository” → 粘贴相同的 GitHub URL。

2. 成员：Customize → Plugins，找到你的市场中列出的 kompa-mcp-plugin，点击安装/连接。

对于没有组织的个人 Free/Pro/Max 账户，这种基于仓库的市场路径不可用——请改用 PLUGIN.md 中的 zip 上传流程。

注意事项 / 限制

• 登录使用与 kompa-chat 的 auth.ts 相同的用户名+密码流程——没有 OAuth，没有浏览器自动化。

• 访问令牌按用户名缓存在进程内，并在过期前 5 分钟刷新。

• topicIds 必须是该账户有权访问的有效 Kompa 项目索引 ID——此服务器不会为你发现或列出它们。

• 在 HTTP 模式下，账户/主题配置仅存在于该 MCP 会话的内存中——关闭对话/会话后配置即丢失，下一个会话必须再次调用 configure_account。