内容
# EMMA MCP — 定制市政金融代理，用于 Blaylock Van
*纽约大学斯特恩商学院咨询顶点项目 · 2026年春季 · 马可·菲格罗亚，贾斯汀·甘吉安，安德鲁·凯，艾萨克·米兹拉希，罗珊·拉贾 · 马西奥诺教授*
---
## 这是什么
一个**自定义MCP（模型上下文协议）服务器**，允许克劳德直接从MSRB的EMMA网站读取市政债券新发行市场。这是我们顶点项目层次结构中的第4级示例 — 一个公司拥有的连接到数据来源的连接器，而没有供应商覆盖。
**EMMA** — 市政证券规则制定委员会运营的电子市政市场访问网站 — 是美国销售的每个市政债券的官方公共记录簿。新发行日历、官方声明、CUSIP级别的详细信息、近期交易价格：都在EMMA上。它没有公共API。
这个MCP公开了**18种工具**和**2种资源**（一个`CLAUDE.md`规则文件和一个`EMMA_ABBREVIATIONS.md`词汇表），克劳德在连接时自动加载。安装完成后，银行家可以向克劳德提出自然语言问题，例如 *"拉取每个未偿还的拉迪儿童医院债券，并下载最新的官方声明"*，克劳德在大约20秒内执行整个链条 — 搜索 → 发行人查找 → 详情 → PDF下载 → 文本提取。
有关完整的推介和为什么它对Blaylock很重要，请参见`USAGE.md` → *为什么存在*。
---
## 先决条件
您的笔记本电脑需要四样东西。如果缺少任何一项，请参阅下面的安装说明。
| 需求 | 内容 | 安装检查 |
|---|---|---|
| **克劳德桌面版** | Anthropic 的原生 macOS/Windows 客户端（MCP主机） | [claude.ai/download](https://claude.ai/download) |
| **Python 3.10+** | 服务器运行时 | Mac: `python3 --version` · Win: `python --version` |
| **uv** | Python 包管理器（自动处理虚拟环境） | `uv --version` |
| **Playwright Chromium** | 服务器驱动EMMA的无头浏览器 | 通过以下命令安装 |
---
## 安装 — Mac
```bash
# 1. 将此文件夹解压到合理的位置
cd ~/Downloads
unzip emma-mcp.zip -d ~/emma-mcp
cd ~/emma-mcp
# 2. 如果您没有uv：
brew install uv
# 3. 创建虚拟环境 + 安装依赖项（一条命令）
uv sync
# 4. 安装Playwright驱动的无头浏览器
uv run playwright install chromium
# 5. 服务器烟雾测试（可选 — 确认启动）
uv run python server.py
# 您应该看到服务器启动并等待标准输入。
# 按Ctrl+C停止。
```
### 连接到克劳德桌面版（Mac）
1. 打开克劳德桌面版 → **设置** → **开发者** → **编辑配置**。这将打开 `claude_desktop_config.json`。
2. 在 `mcpServers` 对象中添加一个 `emma` 条目。使用 `uv sync` 刚刚创建的 `.venv/bin/python` 的**绝对路径**和 `server.py` 的**绝对路径**：
```json
{
"mcpServers": {
"emma": {
"command": "/Users/YOURNAME/emma-mcp/.venv/bin/python",
"args": ["/Users/YOURNAME/emma-mcp/server.py"]
}
}
}
```
3. 保存，完全退出克劳德桌面版（`Cmd+Q`，而不仅仅是关闭窗口），然后重新打开。
4. 在新的聊天中，作曲家中的锤子图标现在应该列出EMMA工具。
---
## 安装 — Windows
```powershell
# 1. 解压此文件夹，例如到C:\emma-mcp
cd C:\emma-mcp
# 2. 如果您没有Python：从python.org安装（3.10或更高版本）。
# 在安装过程中选中“将Python添加到PATH”。
# 3. 安装uv
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
# 4. 创建虚拟环境 + 安装依赖项
uv sync
# 5. 安装Playwright的Chromium
uv run playwright install chromium
# 6. 烟雾测试
uv run python server.py
# 按Ctrl+C停止。
```
### 连接到克劳德桌面版（Windows）
1. 在文本编辑器中打开 `%APPDATA%\Claude\claude_desktop_config.json`。（将该路径粘贴到资源管理器地址栏中 — Windows将 `%APPDATA%` 解析为 `C:\Users\YOU\AppData\Roaming`。）
2. 在JSON路径中使用**正斜杠或双反斜杠** — Windows单个反斜杠会破坏JSON：
```json
{
"mcpServers": {
"emma": {
"command": "C:/emma-mcp/.venv/Scripts/python.exe",
"args": ["C:/emma-mcp/server.py"]
}
}
}
```
3. 保存，完全退出克劳德桌面版（右键单击系统托盘图标 → *退出*），重新打开。
4. 在作曲家中检查锤子图标以获取EMMA工具。
---
## 第一个提示 — 60秒验证
打开一个新的克劳德桌面聊天窗口并粘贴：
> *使用EMMA MCP拉取下周的新发行日历。过滤到纽约州。返回一个干净的表格，包含发行人、面值、日期和部门。*
您应该看到克劳德调用 `get_new_issue_calendar` 并带有 `state="NY"`，在几秒钟内返回大约10-25行，并格式化为带有EMMA网址的表格。如果有效，则其他所有工具都以相同的方式工作。
对于更令人印象深刻的演示，请尝试：
> *在EMMA上找到拉迪儿童医院，拉取其未偿还债券，获取最新问题的详细信息，下载官方声明，并总结评级语言和前10页的募集资金用途。*
这在大约20秒内运行完整的五工具链。
更多演示提示在 `USAGE.md` 中。
---
## 故障排除
**克劳德桌面版重启后不显示EMMA工具。**
- 确认JSON有效（`python3 -m json.tool < claude_desktop_config.json` — 无输出 = 好）。
- 确认配置中的两个路径都是绝对路径且存在。相对路径和 `~` 不起作用。
- 完全退出克劳德桌面版（`Cmd+Q` / 系统托盘 *退出*）— 关闭窗口会使其继续运行。
- 在 `~/Library/Logs/Claude/mcp*.log` （Mac）或 `%APPDATA%\Claude\logs\mcp*.log` （Windows）中检查克劳德桌面版的MCP日志以获取特定错误。
**`playwright install chromium` 挂起或失败。**
- 首次安装下载约150 MB，家庭连接需要1-2分钟。请耐心等待。
- 在公司代理后面，设置 `HTTPS_PROXY` 和 `HTTP_PROXY` 然后运行。
**克劳德调用工具时返回“EMMA免责声明循环”或超时。**
- EMMA在首次访问时设置CUSIP免责声明cookie。服务器预先设置了它（`Disclaimer6=msrborg`）但很少情况下EMMA会更改cookie名称。重启克劳德桌面版以重置浏览器上下文。如果持续存在，EMMA可能已关闭 — 在普通浏览器中检查 `https://emma.msrb.org`。
**返回的表格显示 `cusip_hash: ABC123…` 而不是9位CUSIP。**
- 这是故意的，不是错误。EMMA将CUSIP渲染为图像标签（CGS许可规则），因此服务器无法从HTML中读取它们。**官方声明PDF是权威的CUSIP来源。** 使用 `download_official_statement` 然后 `extract_pdf_text` — 封面和内封面带有真实的CUSIP。
**“拉迪儿童医院”搜索结果中找到富兰克林俄亥俄州和匹兹堡宾夕法尼亚州儿童医院，但找不到拉迪。**
- 这是已知的EMMA怪癖，不是服务器错误。拉迪的债券归档在加利福尼亚州的通道（CHFFA / CPFA）下，只有在义务人括号部分才有 *"RADY CHILDRENS"*，而EMMA的QuickSearch确实索引了它，但力度较弱。尝试 `emma_quick_search {query: "rady"}` 或直接搜索通道： `search_issuers_by_state {state: "CA", contains: "health care facilities"}`。完整的义务人查找攻略在 `USAGE.md` → *通道秘籍* 中。
**服务器启动但克劳德说“没有可用的工具”。**
- 您可能编辑了 `server.py`，并且存在Python语法错误。在终端中运行 `uv run python server.py` — 任何错误都会打印到stderr。修复并重启克劳德桌面版。
---
## 此文件夹中有什么
| 文件/文件夹 | 内容 |
|---|---|
| `server.py` | MCP服务器本身 — 约1500行，Python，Playwright。18种工具，2种资源。 |
| `CLAUDE.md` | 布莱洛克合规规则。作为MCP资源 `emma://rules/CLAUDE.md` 加载到每个EMMA会话中。 |
| `EMMA_ABBREVIATIONS.md` | EMMA的电报式发行人名称缩写（HOSP，AUTH，SR，CMNTY等）+通道秘籍。作为资源 `emma://rules/EMMA_ABBREVIATIONS.md` 加载。 |
| `README.md` | 此文件。 |
| `USAGE.md` | 扩展参考：18种工具，规范的工作流程链，示例银行提示，注意事项。 |
| `pyproject.toml`，`uv.lock` | Python依赖项清单。 |
| `_demo_pulse.py` | 幻灯片准备期间使用的一次性驱动程序 — 直接调用MCP以便我们截取输出截图。不需要运行服务器。 |
| `_fetch_os_pdfs.py` | 配套脚本，批量下载用于顶点项目第2层（Cowork）演示的OS PDF。不需要运行服务器。 |
| `os_pdfs/` | 通过MCP在测试期间下载的示例官方声明。根据需要保留或删除 — 文件夹在第一次 `download_official_statement` 调用时自动重新创建。 |
---
## 单行版本
我们构建了供应商不提供的EMMA MCP，通过与每个市场连接器相同的协议将其连接到克劳德，并使用银行家可以阅读和编辑的纯Markdown规则文件进行管理。这就是当公司实际拥有自己的工具时，Tier 4的样子。
