内容
# ICICLE AI 组件 MCP
[](https://github.com/ICICLE-ai/catalog_mcp?tab=MIT-1-ov-file)
ICICLE AI 组件 MCP 允许开发者使用 AI 驱动的 IDE 来探索 ICICLE 组件，并在 IDE 中直接从聊天窗口实施、实验和迭代。它通过 MCP 暴露了用于列出、搜索和检索组件元数据的工具。
标签：软件
## 致谢
*国家科学基金会（NSF）资助的智能网络环境计算学习 AI 研究所（ICICLE）（OAC 2112606）*
## 问题报告
请在 https://github.com/ICICLE-ai/catalog_mcp/issues 上报告问题，并附上您的 IDE、Python 版本和完整的错误消息或堆栈跟踪。
---
# 教程
## 快速入门
前提条件：
- Python 3.10+
- 可以访问互联网以获取 catalog YAML
步骤：
1) 创建并激活虚拟环境。
```bash
python3 -m venv .venv
source .venv/bin/activate
```
2) 安装依赖项。
```bash
pip install -r requirements.txt
```
3) 运行 MCP 服务器。
```bash
python server.py
```
4) 将您的 MCP 客户端连接到 stdio 服务器（Cursor MCP 设置）。
预期结果：
- MCP 工具（如 `list_components` 和 `search_components`）返回目录数据。
## 从 Cursor 或 Claude Desktop 连接
前提条件：
- 服务器已安装，可以使用 `python server.py` 运行。
步骤（Cursor）：
1) 在 `.cursor/mcp.json` 处创建本地 MCP 配置文件。
```json
{
"mcpServers": {
"icicle-catalog": {
"command": "./.venv/bin/python",
"args": ["./server.py"]
}
}
}
```
2) 在 Cursor 中，打开 MCP 设置并启用 `icicle-catalog` 服务器。
3) 在聊天窗口中，询问类似的问题：“列出 2025-07 版本的组件。”
步骤（Claude Desktop）：
1) 在 `.claude/mcp.json` 处创建本地 MCP 配置文件。
```json
{
"mcpServers": {
"icicle-catalog": {
"command": "./.venv/bin/python",
"args": ["./server.py"]
}
}
}
```
2) 在 Claude Desktop MCP 设置中启用服务器。
3) 询问：“搜索 Foundation AI 的组件。”
预期结果：
- IDE 可以直接从聊天窗口调用 `list_components` 和 `search_components` 等工具。
示例聊天请求和响应：
```
用户：给我展示与 Foundation AI 相关的 ICICLE 组件。
助手：我找到了 7 个组件。以下是前 3 个：[组件列表...]
```
---
# 操作指南
## 按关键词搜索
问题：
- 查找匹配查询字符串的组件。
步骤：
1) 请求 IDE 聊天窗口搜索目录。
示例：
```
用户：查找与 Foundation AI 相关的 ICICLE 组件。
助手：我找到了 7 个组件。以下是前 3 个：[组件列表...]
```
JSON 工具调用（高级）：
```json
{"tool": "search_components", "args": {"query": "Foundation AI"}}
```
提示：
- 使用更广泛的术语以增加召回率。
故障排除：
- 如果结果为空，请检查网络访问和目录 URL。
## 按版本过滤
问题：
- 列出目标版本的组件。
步骤：
1) 请求 IDE 聊天窗口列出指定版本的组件。
示例：
```
用户：列出 2025-07 版本的所有 ICICLE 组件。
助手：我找到了 42 个组件，版本为 2025-07。以下是前 10 个：[组件列表...]
```
JSON 工具调用（高级）：
```json
{"tool": "list_components", "args": {"target_release": "2025-07"}}
```
提示：
- 结合 `primary_thrust` 和 `public_access` 以获得更窄的结果。
故障排除：
- 如果请求超时，请重试或增加 `CATALOG_TIMEOUT`。
---
# 解释
## 概述
核心概念：
- 服务器通过 HTTPS 获取 YAML 目录，并暴露 MCP 工具和资源。
- 工具返回紧凑的摘要，而资源暴露完整的组件记录。
架构：
- `server.py` 定义了 FastMCP 服务器和工具处理程序。
- HTTP 会话处理目录获取的重试和超时。
- 传输方式为 stdio；客户端和服务器之间的消息为 JSON-RPC 2.0。
设计决策：
- stdio 传输方式保持了与基于 IDE 的 MCP 客户端的简单集成。
- 紧凑的列表/搜索响应减少了有效载荷大小和延迟。
概念流程：
```
[MCP 客户端] <-> stdio/JSON-RPC 2.0 <-> [FastMCP 服务器] -> HTTPS -> [目录 YAML]
```
