PubSub MCP
探索发布/订阅消息作为模型上下文协议（MCP）服务器和AI代理的通信策略。
目录
关于
本项目探索使用发布/订阅消息传递（通过NATS JetStream和Dapr）作为MCP服务器和AI服务之间的通信层。 传统的MCP实现使用stdio或HTTP传输进行直接的客户端-服务器通信。 该项目研究了发布/订阅模式是否可以实现更灵活、可扩展和解耦的AI代理架构。
正在探索的关键问题：
- MCP工具调用能否通过发布/订阅消息有效路由？
- 异步发布/订阅如何影响LLM采样请求/响应流？
- 通过消息队列将MCP客户端与服务器解耦的好处和权衡是什么？
- 发布/订阅能否通过共享MCP工具启用多代理协作模式？
建筑
该存储库演示了基于发布/订阅的MCP架构，其中包含两个主要服务：
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ │ │ │ │ │
│ AI-SVC │◄────────┤ NATS/JetStream├────────►│ readme-mcp │
│ │ │ + Dapr │ │ (MCP Server)│
│ LLM │ │ │ │ │
│ Sampling │ │ Pub/Sub │ │ MCP Tools │
│ │ │ │ │ │
└──────────────┘ └──────────────┘ └──────────────┘
│ │
│ │
└─────── Tool Calls ──────────► │
│
◄─────── Tool Responses ─────────────────────────────┘沟通模式：
- 工具请求：
mcp-tool-requests→ 自述mcp过程→mcp-tool-responses - LLM取样： 自述文件mcp→
ai-stream→ ai svc（OpenAI）→ai-stream-responses
基础设施：
- NATS JetStream： 发布/订阅的消息代理
- Dapr： 标准化酒吧/酒吧、州管理的服务网格
- PostgreSQL： Dapr的状态存储
- Docker编写： 当地发展环境
主要特点
- 异步MCP工具执行： MCP工具调用通过发布/订阅主题路由，而不是直接HTTP/stdio
- 解耦服务： AI代理和MCP服务器通过消息队列而不是直接连接进行通信
- LLM采样集成： MCP服务器可以通过发布/订阅请求LLM采样，而无需与AI服务紧密耦合
- TS实施效果： 使用Effect TS演示用于类型安全、可组合服务的函数式编程模式
- CloudEvents标准： 所有发布/订阅消息均遵循CloudEvents规范
- MCP服务器示例： readme-mcp演示了readme验证、生成和AI支持的建议
入门指南
先决条件
# Required software
Node.js >= 22.0.0
npm >= 9.0.0
Docker & Docker Compose
Dapr CLI
# Install Dapr CLI (macOS)
brew install dapr/tap/dapr-cli
dapr init快速开始
最快的入门方法是遵循详细的快速入门指南：
看 ai-mcp-quickstart.md 有关分步设置说明。
快速概述：
# 1. Start infrastructure (NATS, Dapr, PostgreSQL)
docker-compose -f docker-compose.ai-mcp.yml up -d
# 2. Initialize NATS stream
cd src/ai-svc
npm run init-stream
# 3. Start ai-svc with Dapr (Terminal 1)
cd src/ai-svc
npm install && npm run build
dapr run --app-id ai-svc --app-port 3004 --dapr-http-port 3500 \
--components-path ../dapr/components.local -- npm run dev
# 4. Start readme-mcp with Dapr (Terminal 2)
cd src/mcps/readme-mcp
npm install && npm run build
dapr run --app-id readme-mcp --app-port 3005 --dapr-http-port 3502 \
--components-path ../dapr/components.local -- npm run dev
# 5. Run integration tests (Terminal 3)
cd src/mcps/readme-mcp
export OPENAI_API_KEY=your-key-here
npm test src/__tests__/integration/项目结构
pubsub-mcp/
├── src/
│ ├── ai-svc/ # AI service for LLM sampling
│ │ ├── src/
│ │ ├── README.md # Detailed ai-svc documentation
│ │ └── package.json
│ ├── mcps/
│ │ └── readme-mcp/ # MCP server for README tools
│ │ ├── src/
│ │ ├── README.md # Detailed readme-mcp documentation
│ │ └── package.json
│ └── dapr/
│ └── components.local/ # Dapr component configurations
├── docs/
│ ├── guides/
│ │ └── effect-ts.standards.md # Effect-TS coding standards
│ └── templates/
│ └── __README.md # README template
├── ai-mcp-quickstart.md # Quick start guide
├── docker-compose.ai-mcp.yml # Local development infrastructure
└── README.md # This file文档
详细文档按服务和主题组织：
服务文档
- ai svc自述 -人工智能服务架构、配置和部署
- 自述文件mcp自述文件 -MCP服务器实现、API参考和工具文档
指南
架构文档
有关详细的体系结构信息，请参阅：
- MCP集成流程： ai-mcp quickstart.md架构概述
- 数据流图： src/mcps/readme-mcp/readme.md#体系结构
发展
代码组织
这是一个具有独立服务的monorepo风格的项目：
- ai svc： 用于LLM采样的独立Node.js服务
- 自述文件mcp： 用于README操作的独立MCP服务器
- dapr/components.local： 共享Dapr组件配置
每个服务都有自己的：
package.json和依赖关系tsconfig.json用于TypeScript编译README.md带有特定服务文档- 测试套件和测试配置
开发工作流程
# Install dependencies for a service
cd src/ai-svc # or src/mcps/readme-mcp
npm install
# Build
npm run build
# Run tests
npm test
# Run with Dapr
npm run dapr:run添加新的MCP服务器
要添加新的MCP服务器以探索其他发布/订阅模式：
- 在下创建新目录
src/mcps/your-mcp-server/ - 使用实现MCP服务器
@modelcontextprotocol/sdk - 与Dapr发布/订阅集成，用于工具请求/响应
- 在中添加Dapr组件配置
src/dapr/components.local/ - 如果需要额外的基础设施，请更新docker compose
- 特定于服务的README中的文档
看 自述文件mcp 作为参考实现。
测试
单元测试
每个服务都有自己的测试套件：
# Test ai-svc
cd src/ai-svc
npm test
# Test readme-mcp
cd src/mcps/readme-mcp
npm test集成测试
集成测试验证服务之间的发布/订阅通信：
# Ensure services are running first (see Quick Start)
cd src/mcps/readme-mcp
export OPENAI_API_KEY=your-key-here
npm test src/__tests__/integration/集成测试覆盖率：
- 通过发布/订阅调用MCP工具（验证自述、生成自述、检查完整性）
- LLM采样请求/响应流程（建议改进）
- 并发请求处理
- 错误处理和超时
有关详细的测试文档，请参阅 ai-mcp quickstart.md#测试覆盖率.
许可证
此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。
联系
项目链接：