Cardano MCP Server

Cardano MCP Server

概要

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 の下でライセンスされています。詳細は LICENSE ファイルをご覧ください。

謝辞

• TypeScript SDK を提供してくださった Model Context Protocol チーム
• ドキュメントとリソースを提供してくださった Cardano コミュニティ
• 貢献者とメンテナー

モジュール

ナレッジモジュール

ナレッジモジュールは、さまざまなソースからドキュメントを処理し、アクセスする機能を提供します。HTML および Markdown ドキュメントから構造化されたコンテンツを取得、解析、検証、抽出するコンポーネントが含まれています。

主な機能：

• HTML の検証とクリーニング
• セクションの抽出とメタデータの生成
• Markdown の処理
• リトライ機能を備えたエラー処理
• テストカバレッジ約 92.39%

詳細については、ナレッジモジュールのドキュメントをご覧ください。

関連ドキュメント：

• パーサーのテスト方法

リポジトリモジュール

リポジトリモジュールは、GitHub リポジトリのインデックス作成、クエリ、管理機能を提供します。このモジュールにより、リポジトリのコンテンツを取得して処理し、コンテキストを考慮した操作に利用できます。

主な機能：

• GitHub リポジトリの取得とインデックス作成
• README ファイルを処理して構造化されたコンテンツを作成
• 利用可能なリポジトリのレジストリを維持
• リポジトリのコンテンツを効率的なアクセスのために保存
• ブランチカバレッジ 80% 超

詳細については、リポジトリのドキュメントをご覧ください。

関連ドキュメント：

• 統合ガイド
• テストガイド
• テスト設定

エラー処理システム

エラー処理システムは、アプリケーション全体でエラーを管理する包括的な方法を提供します。専用のエラークラス、ドメイン固有のエラーを作成するファクトリー、一般的なエラー状況に対応するハンドラーが含まれています。

主な機能：

• シリアライズをサポートする AppError 基底クラス
• ドメイン別（ネットワーク、ドキュメントなど）のエラーファクトリー
• 設定可能なリトライロジックを備えたリトライハンドラー
• 一貫性のあるエラーコードとステータスコード
• テストカバレッジ約 93%

詳細については、エラー処理のドキュメントをご覧ください。

コンテキスト組み立てモジュール（近日公開）

コンテキスト組み立てモジュールは、ナレッジモジュールとリポジトリモジュールをつなぐ役割を果たし、LLM のプロンプトや応答に包括的なコンテキスト情報を提供します。

主な機能：

• ドキュメントとリポジトリからの複数ソース検索
• ユーザーのクエリに基づく関連性のランキング
• LLM のコンテキストウィンドウの最適化
• ソースの帰属表示と信頼度インジケーター

詳細については、コンテキスト組み立てのドキュメントをご覧ください。