Cardano MCP Server

Cardano MCP 服务

概述

Cardano Model Context Protocol（MCP）服务是一个专用网关，可简化应用开发者与 Cardano 区块链的集成。它基于官方 MCP TypeScript SDK 构建，可便捷地访问 Cardano 文档、工具和最佳实践。

核心目标

1. 文档集成

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

2. 前端开发支持

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

3. 智能合约开发

   • 安全优先的合约模板
   • 自动化安全验证
   • 确保遵循最佳实践

架构

src/
├── server/           # MCP Server implementation
│   ├── mcpServer.ts  # CardanoMcpServer class
│   ├── integrations/ # Module integration
│   ├── resources/    # MCP resources
│   ├── tools/        # MCP tools
│   └── prompts/      # MCP prompts
├── knowledge/        # Documentation and knowledge base
│   └── processors/   # Documentation processors
├── repositories/     # Repository indexing module
│   ├── configs/      # Repository configurations
│   ├── processors/   # Repository content processors
│   ├── githubClient.ts # GitHub API client
│   ├── indexer.ts    # Repository indexer
│   ├── registry.ts   # Repository registry
│   ├── storage.ts    # Content storage
│   └── types.ts      # Type definitions
├── types/            # Type definitions
├── utils/            # Utility functions
│   └── errors/       # Error handling system
│       ├── core/     # Core error classes
│       ├── factories/# Error factory classes
│       ├── handlers/ # Error handlers (retry, etc.)
│       └── types/    # Error type definitions
├── tools/            # Development tools and utilities
├── prompts/          # Prompt templates and configurations
└── index.ts          # MCP server entry point

技术栈

• TypeScript
• Model Context Protocol SDK
• 使用 Jest 进行测试
• 使用 ESLint + Prettier 保证代码质量

开发方式

• 测试驱动开发（TDD）
• KISS（保持简单，愚蠢）原则
• DRY（不要重复自己）原则
• 安全优先思维
• 全面的错误处理
• 持续集成／持续交付（CI/CD）
  • 使用 GitHub Actions 工作流进行自动化测试和质量保证
  • ESLint、TypeScript 类型检查和 Prettier 格式验证
  • 并行执行测试以提升性能
  • 强制执行测试覆盖率阈值（行覆盖率 >90%）
  • 文档生成（计划中）

开始使用

先决条件

• Node.js >= 16.0.0
• npm 或 yarn
• TypeScript 知识
• Cardano 基础知识

安装

# Install dependencies
npm install

# Build the project
npm run build

# Start the MCP server with stdio transport
npm start

# Start the MCP server with SSE transport
npm run start:sse

测试

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

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

  • knowledge/：知识模块组件的测试
  • repositories/：存储库索引模块的测试
  • utils/：实用函数的测试，包括错误处理
  • server/：服务组件的测试

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

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

运行测试

# Run all tests
npm test

# Run tests with coverage report
npm run test:coverage

# Run specific test categories
npm run test:knowledge     # Run knowledge module tests
npm run test:repository    # Run repository tests
npm run test:errors        # Run error handling tests
npm run test:server        # Run server integration tests
npm run test:debug         # Run tests with debugging options

# Run standalone tests (without mock server)
npm run test:repository:standalone  # Run repository tests without server
npm run test:errors:standalone      # Run error tests without server

有关测试的完整文档，请参阅 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：独立存储库测试配置

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

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

使用示例

访问文档

// Access Blockfrost API documentation
const docs = await client.readResource('docs://blockfrost/api');

// Get smart contract security patterns
const patterns = await client.readResource('docs://cardano/contracts/security');

访问存储库

// Access a GitHub repository README
const readme = await client.readResource('repository://input-output-hk/cardano-node');

// Get a specific file from a repository
const file = await client.readResource('repository://input-output-hk/cardano-node/file/README.md');

// List files in a repository
const files = await client.readResource('repository://input-output-hk/cardano-node/files');

钱包集成

// Generate wallet connection code
const result = await client.callTool({
  name: 'generate-wallet-connector',
  arguments: {
    walletType: 'nami',
    network: 'testnet',
  },
});

智能合约开发

// Validate smart contract security
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% 的测试覆盖率

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

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

上下文组装模块将作为知识模块与仓库模块之间的桥梁，为大模型提示词和响应提供全面的上下文信息。

主要功能：

• 从文档和仓库中检索多源信息
• 根据用户查询进行相关性排序
• 优化大模型的上下文窗口
• 提供来源归属信息和置信度指标

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