Cardano MCP 服务器

概述

Cardano 模型上下文协议 (MCP) 服务器是一个专门的网关，旨在简化应用开发者对 Cardano 区块链的集成。它基于官方 MCP TypeScript SDK 构建，提供对 Cardano 文档、工具和最佳实践的简化访问。

核心目标

1. 文档集成

   • 统一访问 Cardano 生态系统文档
   • 与 Blockfrost、Maestro 和其他提供商 API 集成
   • 智能合约开发指南和模式

2. 前端开发支持

   • 钱包连接模板和实用程序
   • 交易构建模式
   • UI 组件模板

3. 智能合约开发

   • 安全优先的合约模板
   • 自动化安全验证
   • 最佳实践强制执行

架构

src/
├── server/           # MCP 服务器实现
│   ├── mcpServer.ts  # CardanoMcpServer 类
│   ├── integrations/ # 模块集成
│   ├── resources/    # MCP 资源
│   ├── tools/        # MCP 工具
│   └── prompts/      # MCP 提示
├── knowledge/        # 文档和知识库
│   └── processors/   # 文档处理器
├── repositories/     # 仓库索引模块
│   ├── configs/      # 仓库配置
│   ├── processors/   # 仓库内容处理器
│   ├── githubClient.ts # GitHub API 客户端
│   ├── indexer.ts    # 仓库索引器
│   ├── registry.ts   # 仓库注册表
│   ├── storage.ts    # 内容存储
│   └── types.ts      # 类型定义
├── types/            # 类型定义
├── utils/            # 实用函数
│   └── errors/       # 错误处理系统
│       ├── core/     # 核心错误类
│       ├── factories/# 错误工厂类
│       ├── handlers/ # 错误处理程序（重试等）
│       └── types/    # 错误类型定义
├── tools/            # 开发工具和实用程序
├── prompts/          # 提示模板和配置
└── index.ts          # MCP 服务器入口点

技术栈

• TypeScript
• 模型上下文协议 SDK
• Jest 用于测试
• ESLint + Prettier 用于代码质量

开发方法

• 测试驱动开发 (TDD)
• KISS (Keep It Simple, Stupid) 原则
• DRY (Don't Repeat Yourself) 原则
• 安全优先的思维模式
• 全面的错误处理
• 持续集成/持续交付 (CI/CD)
  • GitHub Actions 工作流，用于自动化测试和质量保证
  • ESLint、TypeScript 类型检查和 Prettier 格式验证
  • 并行测试执行，以提高性能
  • 测试覆盖率阈值强制执行（>90% 行覆盖率）
  • 文档生成（计划中）

快速入门

前提条件

• Node.js >= 16.0.0
• npm 或 yarn
• TypeScript 知识
• 基本 Cardano 理解

安装

# 安装依赖
npm install

# 构建项目
npm run build

# 使用 stdio 传输启动 MCP 服务器
npm start

# 使用 SSE 传输启动 MCP 服务器
npm run start:sse

测试

该项目使用 Jest 进行测试，采用模块化配置方法。测试按模块和类型组织：

• 单元测试: 位于 tests/unit/

  • knowledge/: 知识模块组件的测试
  • repositories/: 仓库索引模块的测试
  • utils/: 实用函数（包括错误处理）的测试
  • server/: 服务器组件的测试

• 集成测试: 位于 tests/integration/

  • 验证多个组件之间交互的测试

运行测试

# 运行所有测试
npm test

# 运行带有覆盖率报告的测试
npm run test:coverage

# 运行特定测试类别
npm run test:knowledge     # 运行知识模块测试
npm run test:repository    # 运行仓库测试
npm run test:errors        # 运行错误处理测试
npm run test:server        # 运行服务器集成测试
npm run test:debug         # 运行带有调试选项的测试

# 运行独立测试（不带模拟服务器）
npm run test:repository:standalone  # 运行不带服务器的仓库测试
npm run test:errors:standalone      # 运行不带服务器的错误测试

有关测试的全面文档，请参阅 TESTING.md。

我们使用模块化方法进行测试配置：

• jest.base.config.js: 所有测试套件共享的基础配置
• jest.knowledge.config.js: 知识模块测试的配置
• jest.repository.config.js: 仓库模块测试的配置
• jest.server.config.js: 服务器集成测试的配置
• jest.errors.config.js: 错误处理测试的配置
• jest.errors.standalone.js: 独立错误测试配置
• jest.repository.standalone.js: 独立仓库测试配置

有关测试类别和最近改进的详细信息，请参阅：

• 测试类别
• 测试配置修复

使用示例

文档访问

// 访问 Blockfrost API 文档
const docs = await client.readResource('docs://blockfrost/api');

// 获取智能合约安全模式
const patterns = await client.readResource('docs://cardano/contracts/security');

仓库访问

// 访问 GitHub 仓库 README
const readme = await client.readResource('repository://input-output-hk/cardano-node');

// 从仓库获取特定文件
const file = await client.readResource('repository://input-output-hk/cardano-node/file/README.md');

// 列出仓库中的文件
const files = await client.readResource('repository://input-output-hk/cardano-node/files');

钱包集成

// 生成钱包连接代码
const result = await client.callTool({
  name: 'generate-wallet-connector',
  arguments: {
    walletType: 'nami',
    network: 'testnet',
  },
});

智能合约开发

// 验证智能合约安全性
const result = await client.callTool({
  name: 'validate-contract',
  arguments: {
    code: contractCode,
  },
});

项目文档

• CHANGELOG.md - 版本历史和变更
• CONTRIBUTING.md - 贡献指南
• CODE_OF_CONDUCT.md - 社区标准
• SECURITY.md - 安全策略和实践
• TESTING.md - 全面的测试指南

许可证

该项目根据 MIT 许可证获得许可 - 有关详细信息，请参阅 LICENSE 文件。

致谢

• Model Context Protocol 团队提供的 TypeScript SDK
• Cardano 社区提供的文档和资源
• 贡献者和维护者

模块

知识模块

知识模块提供处理和访问来自各种来源的文档的功能。它包括用于从 HTML 和 Markdown 文档中获取、解析、验证和提取结构化内容的组件。

主要特点：

• HTML 验证和清理
• 章节提取和元数据生成
• Markdown 处理
• 具有重试功能的错误处理
• ~92.39% 测试覆盖率

有关详细信息，请参阅 知识模块文档。

其他文档：

• 解析器测试方法

仓库模块

仓库模块提供用于索引、查询和管理 GitHub 仓库的功能。该模块能够检索和处理仓库内容，使其可用于上下文感知操作。

主要特点：

• 获取和索引 GitHub 仓库
• 处理 README 文件以获取结构化内容
• 维护可用仓库的注册表
• 存储仓库内容以实现高效访问

• 80% 分支覆盖率

有关详细信息，请参阅 仓库文档。

其他文档：

• 集成指南
• 测试指南
• 测试配置

错误处理系统

错误处理系统提供了一种全面的方法来管理整个应用程序中的错误。它包括专门的错误类、用于创建特定领域错误的工厂以及用于常见错误场景的处理程序。

主要特点：

• 具有序列化支持的 AppError 基类
• 用于不同领域（网络、文档等）的错误工厂
• 具有可配置重试逻辑的重试处理程序
• 一致的错误代码和状态代码
• ~93% 测试覆盖率

有关详细信息，请参阅 错误处理文档。

上下文组装模块（即将推出）

上下文组装模块将充当知识模块和仓库模块之间的桥梁，为 LLM 提示和响应提供全面的上下文信息。

主要特点：

• 从文档和仓库进行多源检索
• 基于用户查询的相关性排名
• LLM 的上下文窗口优化
• 来源归属和置信度指标

有关详细信息，请参阅 上下文组装文档。