MCP Stark Brain（支付）

本地 MCP 服务器，帮助支付团队处理日常工作：

• 查询 Python 微服务使用的架构模式。

• 查找微服务规格（每个服务的目标和职责）。

• 理解支付处理流程。

• 结合文档搜索与 GCP 分析（Datastore + Cloud Logging / Log Explorer），对客户成功（CS）工单进行分类和调查。

• 使用你的 ECDSA 项目凭据，在 development（默认）或 sandbox（仅在明确要求时）环境中调用 Stark Bank API。

它针对 starkbank/alexandria 中的文档执行 RAG，使用你的私钥签署 Stark Bank API 请求，并使用你自己的 gcloud 身份（ADC）运行 GCP 查询。

1. 工作原理

IDE / LLM  --stdio-->  MCP server
                         |-- Docs (RAG): fetch alexandria via GitHub PAT -> local vector index
                         |-- Stark Bank API: ECDSA-signed HTTP to development (default) / sandbox
                         |-- GCP: Datastore + Cloud Logging via your gcloud ADC (project per call)

• 文档优先采用远程内容（不保留 git clone）。 服务器通过 GitHub API 下载仓库压缩包（一次请求获取全部内容）来构建本地嵌入索引。只有向量索引在本地缓存。

• 感知速率限制。 当 GitHub 配额不足时，服务器会建议克隆仓库并切换到 local 模式（参见第 10 节）。

• Stark Bank API 默认使用 development（https://development.api.starkbank.com）。只有在用户明确要求后，才能使用带有 environment="sandbox" 的工具调用沙盒。绝不使用生产环境。

• GCP 项目按调用传入。 没有固定的项目环境变量：每次查询都接受显式的 project，因此你可以在同一会话中切换微服务项目，而无需修改全局 gcloud config。

• GCP 不使用服务账号密钥。 GCP 访问使用你的个人 ADC 凭据，从而保留每位用户的权限和审计跟踪。

2. 前提条件

• Python 3.12（构建/安装包所需）。 chromadb 和 fastembed（通过 onnxruntime）目前还不能可靠地为更新版本的解释器提供预编译 wheel，因此项目固定 requires-python = ">=3.11,<3.13"，下面的每条命令也明确针对 3.12 —— 不要未检查版本就替换系统中的默认 python3。

• uv（推荐）或 pipx 来安装包。

• Google Cloud SDK（gcloud）。

使用 uv 检查/安装固定的 Python 版本（不会影响系统 Python）：

uv python install 3.12

3. 生成你的 GitHub PAT

每个开发者生成自己的 PAT（绝不共享，绝不提交）。alexandria 是私有仓库，属于 starkbank 组织，因此哪种令牌类型可用取决于组织的令牌策略——选择前请先阅读以下两个选项。

选项 A：细粒度 PAT（先尝试这个）

1. GitHub -> Settings -> Developer settings -> Fine-grained tokens -> Generate new token。

2. Resource owner: starkbank。

3. Repository access: Only select repositories -> starkbank/alexandria。

4. Permissions: Repository permissions -> Contents: Read-only。

5. 生成并复制令牌（你将在 mcp.json 中将其设置为环境变量）。

6. 在 https://github.com/settings/personal-access-tokens 检查其状态。 如果组织需要审批，它会显示为 Pending，并且在获批前每次请求都会返回 404。请 starkbank 组织所有者到组织的 Settings -> Personal access tokens -> Pending requests 下审批，或跳到选项 B。

选项 B：经典 PAT（组织不批准细粒度令牌时的备选方案）

经典 PAT 不受上述组织审批步骤的约束，因此如果你的组织限制细粒度令牌，它们会是更快的路径：

1. GitHub -> Settings -> Developer settings -> Tokens (classic) -> Generate new token。

2. 范围：repo（经典令牌对私有仓库没有仅限内容的 scope）。

3. 如果 starkbank 组织强制要求 SSO，请点击新创建令牌旁边的 Configure SSO，并为 starkbank Authorize——未授权的令牌对 starkbank 资源的 404 情况与未获批准的细粒度令牌完全相同。

无论选择哪种方式，安装后，请先运行 diagnose_github_access 工具（参见第 8 节）确认令牌确实可用，然后再依赖它。

4. 使用 GCP 进行身份验证（ADC）

gcloud auth login
gcloud auth application-default login

你不需要在此处设置项目——MCP 会在每次 GCP 工具调用时收到 project。使用 analyze_ticket / resolve_project 获取项目建议。

5. Stark Bank API 凭据（ECDSA）

API 调用使用 ECDSA（secp256k1）进行身份验证，而不是静态 API 密钥。参见官方文档：认证。

1. 生成密钥对（如果还没有的话），并只为开发环境在 Web Banking（Integrations → Project）中注册公钥。

2. 将私钥 PEM 保存在你的机器上——绝不提交，也绝不将公钥放入此仓库（MCP 不需要公钥来签署请求）。

3. 记下创建/注册 Project 后 Web Banking 中显示的 Project ID。

4. 通过环境变量将 MCP 指向 PEM 和 Project ID（参见第 6 步 / 第 11 节）。

私钥的建议存放位置（仓库外）：

mkdir -p ~/.config/mcp-stark-brain
chmod 700 ~/.config/mcp-stark-brain
# copy your privateKey.pem there, then:
chmod 600 ~/.config/mcp-stark-brain/privateKey.pem

默认基础 URL：

6. 构建包（wheel）

在仓库根目录下，始终明确指定解释器为 Python 3.12——不要直接运行 uv build 并依赖 PATH 中恰好排在最前面的 Python：

rm -rf dist  # avoid mixing wheels from a previous version/build
uv build --python 3.12 -o dist

这会在 dist/ 中生成可安装的工件（文件名中的确切版本来自 pyproject.toml 中的 version，当前为 0.2.0）：

dist/
  mcp_stark_brain-0.2.0-py3-none-any.whl
  mcp_stark_brain-0.2.0.tar.gz

将 .whl 分发给开发者（或放到共享位置）。

如果没有 uv：使用 python3.12 -m venv .venv312 创建虚拟环境，激活它，然后运行 pip install build && python -m build -o dist。先用 python3.12 --version 验证——如果找不到该命令，请先安装 Python 3.12 再继续；不要使用不同的主/次版本构建。

7. 在 IDE 中安装 MCP

将 wheel 作为隔离工具安装，再次显式固定 Python 3.12，以使工具的环境与构建/测试时的环境一致。使用通配符，这样你永远不需要手动编辑版本号（也不会意外安装上一次构建遗留下来的过期 wheel）：

# with uv (recommended)
uv tool install --python 3.12 ./dist/mcp_stark_brain-*-py3-none-any.whl

# or with pipx
pipx install --python python3.12 ./dist/mcp_stark_brain-*-py3-none-any.whl

这会将 mcp-stark-brain 命令暴露到你的 PATH 中。

然后将服务器添加到你的 IDE 的 MCP 配置中（例如 Cursor 的 ~/.cursor/mcp.json 或项目的 .cursor/mcp.json）：

{
  "mcpServers": {
    "stark-brain": {
      "command": "mcp-stark-brain",
      "env": {
        "ALEXANDRIA_GITHUB_PAT": "<your-personal-fine-grained-PAT>",
        "STARKBANK_PRIVATE_KEY_PATH": "/Users/you/.config/mcp-stark-brain/privateKey.pem",
        "STARKBANK_PROJECT_ID": "<your-project-id>",
        "STARKBANK_DEV_BASE_URL": "https://development.api.starkbank.com",
        "STARKBANK_SANDBOX_BASE_URL": "https://sandbox.api.starkbank.com"
      }
    }
  }
}

重启/重新加载 IDE，使其加载新的 MCP 服务器。

想在 Tools & MCP 列表中让 stark-brain 旁边显示自定义图标（就像官方 github MCP 显示它的 logo 那样）？参见 cursor-plugin/README.md 了解一个可选的包装器，它将这个相同的配置打包为一个带有 logo 的本地 Cursor 插件。纯装饰性的——如果不在意，可以跳过。

8. 更新已安装的 MCP

每当此仓库发生变化（新工具、错误修复、配置默认值修复等），你都需要一个新的包。命令取决于你最初安装的方式——用错命令是“为什么我的修复没有生效？”这种困惑最常见的来源，因此请选择与第 6 步匹配的那一个：

# 1. Pull the latest source and rebuild the bundle (repo maintainer, or you if you
#    build it yourself). Always clean dist/ first to avoid mixing old/new wheels.
git pull
rm -rf dist
uv build --python 3.12 -o dist

# 2a. If you installed with `uv tool install`, use --reinstall (uv tool upgrade
#     does NOT work for local wheel paths, only for PyPI-published packages):
uv tool install --python 3.12 --reinstall ./dist/mcp_stark_brain-*-py3-none-any.whl

# 2b. If you installed with pipx, uninstall + reinstall (pipx has no local-wheel
#     upgrade command either):
pipx uninstall mcp-stark-brain
pipx install --python python3.12 ./dist/mcp_stark_brain-*-py3-none-any.whl

然后，让 Cursor 真正重新生成服务器进程——你看到的工具列表是该特定 stdio 子进程启动时声明的，因此仅重新安装到磁盘并不能更新它：

1. 首先，确认重新安装确实已生效（在 Cursor 之外，在普通终端中）：

   uv tool list | grep -A2 mcp-stark-brain   # confirm the version bumped
   which mcp-stark-brain

2. 在 Cursor 中关闭/打开服务器——这是无需退出整个应用即可重新生成单个 MCP 服务器的官方支持方式：Cmd+Shift+J -> Tools & MCP -> 找到 stark-brain -> 将其切换为关闭，等待几秒，再切换为打开。

3. 打开一个全新的聊天。 在切换之前已经打开的聊天，即使在服务器重启后，也可能继续显示旧的工具列表。

4. 如果工具看起来仍然陈旧，说明 Cursor 的 Shared Process——每个应用实例一个后台进程，承载所有 MCP 子进程（不是每窗口一个，所以 Developer: Reload Window 不会重启它）——仍在内存中保留旧的子进程。完全退出应用（Cmd+Q，而不仅仅是关闭窗口）并重新打开；这会终止 Shared Process 及其所有 MCP 子进程。

5. 要在协议层面确认而不是猜测：Cmd+Shift+U -> MCP Logs 下拉菜单 -> stark-brain -> 检查 tools/list 响应确实包含新工具名称。如果那里也没有，问题在于安装的包，而不是 Cursor 的缓存——回到第 1 步。

6. 一旦新工具可见，运行 status 工具确认更新已生效（检查 docs_mode、repo、ref、embed_model 是否符合你的预期）。

7. 如果只是文档内容发生了变化（而不是代码），你不需要重新安装任何东西——只需从 IDE 调用 refresh_docs()。

更新时你不需要重新生成 PAT 或重做 gcloud auth；这些凭据与安装的版本无关。

9. 首次运行与用法

• 在第一次调用文档工具时，服务器会获取 alexandria 内容并构建本地索引（下载嵌入模型需要一些时间，只需一次）。

• 使用 refresh_docs 在文档更改后重新同步（增量：仅重新嵌入更改过的文件）。

• status 报告文档模式、索引文件数量、速率限制以及 Stark Bank API 凭据是否已配置（starkbank_api_configured）。

• Stark Bank API 工具默认使用 development。仅在用户明确要求沙盒时传递 environment="sandbox"。

可用工具：

10. 远程与本地模式

• remote（默认）：文档通过你的 PAT 从 GitHub 获取。高效（tarball = 每次刷新 1 个请求），但会消耗你的 GitHub API 预算。

• local：文档从你自己克隆的目录中读取；零 API 使用。

当 GitHub 速率限制接近耗尽时，服务器会警告你并建议切换。切换方法：

# clone the repo once (your own credentials)
git clone git@github.com:starkbank/alexandria.git ~/repos/alexandria

然后要么在 mcp.json 中设置它：

"env": {
  "ALEXANDRIA_GITHUB_PAT": "<pat>",
  "STARK_BRAIN_DOCS_MODE": "local",
  "STARK_BRAIN_DOCS_PATH": "/Users/you/repos/alexandria"
}

或者通过工具在运行时切换：

set_docs_source(mode="local", path="/Users/you/repos/alexandria")
refresh_docs()

11. 配置参考（环境变量）

参见 .env.example。

12. 故障排查

• configuration error: ALEXANDRIA_GITHUB_PAT is required — 在你的 mcp.json 环境中设置 PAT，或切换到 local 模式。

• GitHub 401 — PAT 无效或已过期。请重新生成。

• GitHub 404（“Repo or ref not found”）即使仓库存在 — 对于私有仓库，当资源确实不存在或你的令牌无法看到它时，GitHub 都会返回 404，因此这几乎总是令牌/访问问题，而不是错误的 ALEXANDRIA_REPO/ALEXANDRIA_REF。最常见的原因：细粒度 PAT 仍在等待组织管理员批准（检查 https://github.com/settings/personal-access-tokens — 如果显示 “Pending”，参见 第 3 节 了解批准步骤或 classic-PAT 备用方案）。运行 diagnose_github_access() 进行实时检查，以精确定位此问题。

• GitHub 403 / 速率受限 — 检查 PAT 权限，或克隆并使用 local 模式。

• GCP credentials not found — 运行 gcloud auth application-default login。

• Datastore/Logging 权限错误 — 你查询了一个你无权访问的项目；请选择另一个 project 或申请访问权限。

• 首次运行时模型下载缓慢 — 嵌入模型在首次使用后会缓存到 STARK_BRAIN_CACHE_DIR 下。

• 重新安装后新添加的工具没有显示 — 这是 Cursor 端的陈旧进程问题，不是安装错误（参见 第 8 节 逐步说明）：正在运行的 MCP 子进程不会自行拾取磁盘上的重新安装。在 Tools & MCP 中关闭/重新打开服务器，打开一个新聊天，如果仍然不够，完全退出（Cmd+Q）并重新打开 Cursor。

• STARKBANK_PRIVATE_KEY_PATH is not set / API 工具失败 — 在 mcp.json 中设置你的 PEM 的绝对路径和 STARKBANK_PROJECT_ID（参见 第 5 节）。确认 status().starkbank_api_configured 为 true。

• Stark Bank API 401 / 无效签名 — 项目 ID 错误、PEM 未在该环境中注册，或时钟偏差。确认公钥已在匹配的 Web Banking 环境（开发环境 vs 沙箱）中注册。

13. 安全说明

• 你的 PAT 仅在 Authorization 头中发送，并且永远不会被记录。

• Stark Bank 私钥在请求时从磁盘读取，并且永远不会被记录。

• 不分发任何服务账号密钥；GCP 访问使用你的个人 ADC 身份。

• GCP project 按调用传递——没有共享/硬编码的项目。

• 生产 Stark Bank API 主机会被客户端拒绝。

• .env、*.pem、keys/ 和本地缓存被 git 忽略。

14. 开发

源文件直接放在 src/ 下（没有多余的 src/mcp_stark_brain/ 嵌套）。pyproject.toml 中的构建配置将它们作为 mcp_stark_brain 导入包打包到 wheel 中（packages = ["src"] + sources = {"src" = "mcp_stark_brain"}），因此无论磁盘上的布局如何，入口点和内部导入都保持不变。

这种重命名与可编辑/开发模式安装不兼容（hatchling/pip 的限制），因此 uv sync 配置了 tool.uv.package = false：它只安装依赖项，而不安装项目本身。conftest.py 和 scripts/smoke_test.py 使用 devtools/bootstrap.py 使 import mcp_stark_brain 在不需安装步骤的情况下，直接针对 src/ 用于测试和本地脚本。

uv python install 3.12
uv sync --extra dev --python 3.12
uv run ruff check .
uv run pytest
uv run python scripts/smoke_test.py

要在本地实际尝试服务器（无需构建 wheel）：

uv run --python 3.12 python -c "from devtools.bootstrap import ensure_importable; ensure_importable(); from mcp_stark_brain.server import main; main()"