Cardano MCP Server

Cardano MCP Server

A specialized RAG gateway providing language models with Cardano blockchain knowledge. Enables AI assistants to access documentation, validate smart contracts, understand UTXO patterns, and discover development resources. Built on the MCP TypeScript SDK. Open-source.

Jimmyh-world

Research & Data
Visit Server

README

Cardano MCP Server

Overview

The Cardano Model Context Protocol (MCP) Server is a specialized gateway that simplifies Cardano blockchain integration for application developers. Built on the official MCP TypeScript SDK, it provides streamlined access to Cardano documentation, tools, and best practices.

Core Objectives

  1. Documentation Integration

    • Unified access to Cardano ecosystem documentation
    • Integration with Blockfrost, Maestro, and other provider APIs
    • Smart contract development guides and patterns
  2. Frontend Development Support

    • Wallet connection templates and utilities
    • Transaction building patterns
    • UI component templates
  3. Smart Contract Development

    • Security-first contract templates
    • Automated security validation
    • Best practice enforcement

Architecture

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

Technology Stack

  • TypeScript
  • Model Context Protocol SDK
  • Jest for testing
  • ESLint + Prettier for code quality

Development Approach

  • Test-Driven Development (TDD)
  • KISS (Keep It Simple, Stupid) principle
  • DRY (Don't Repeat Yourself) principle
  • Security-first mindset
  • Comprehensive error handling
  • Continuous Integration/Continuous Delivery (CI/CD)
    • GitHub Actions workflow for automated testing and quality assurance
    • ESLint, TypeScript type checking, and Prettier format verification
    • Parallel test execution for improved performance
    • Test coverage threshold enforcement (>90% line coverage)
    • Documentation generation (planned)

Getting Started

Prerequisites

  • Node.js >= 16.0.0
  • npm or yarn
  • TypeScript knowledge
  • Basic Cardano understanding

Installation

# 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

Testing

The project uses Jest for testing with a modular configuration approach. Tests are organized by module and type:

  • Unit Tests: Located in tests/unit/

    • knowledge/: Tests for the knowledge module components
    • repositories/: Tests for the repository indexing module
    • utils/: Tests for utility functions, including error handling
    • server/: Tests for server components
  • Integration Tests: Located in tests/integration/

    • Tests that verify the interaction between multiple components

Running Tests

# 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

For comprehensive documentation on testing, see TESTING.md.

We use a modular approach to test configuration:

For detailed information on test categories and recent improvements, see:

Usage Examples

Documentation Access

// 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');

Repository Access

// 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');

Wallet Integration

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

Smart Contract Development

// Validate smart contract security
const result = await client.callTool({
  name: 'validate-contract',
  arguments: {
    code: contractCode,
  },
});

Project Documentation

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

  • Model Context Protocol team for the TypeScript SDK
  • Cardano community for documentation and resources
  • Contributors and maintainers

Modules

Knowledge Module

The Knowledge module provides functionality for processing and accessing documentation from various sources. It includes components for fetching, parsing, validating, and extracting structured content from HTML and Markdown documents.

Key features:

  • HTML validation and cleaning
  • Section extraction and metadata generation
  • Markdown processing
  • Error handling with retry capabilities
  • ~92.39% test coverage

For detailed information, see the knowledge module documentation.

Additional documentation:

Repositories Module

The Repositories module provides functionality for indexing, querying, and managing GitHub repositories. This module enables the retrieval and processing of repository content, making it available for context-aware operations.

Key features:

  • Fetch and index GitHub repositories
  • Process README files for structured content
  • Maintain a registry of available repositories
  • Store repository content for efficient access
  • 80% branch coverage

For detailed information, see the repositories documentation.

Additional documentation:

Error Handling System

The Error Handling system provides a comprehensive approach to managing errors throughout the application. It includes specialized error classes, factories for creating domain-specific errors, and handlers for common error scenarios.

Key features:

  • AppError base class with serialization support
  • Error factories for different domains (network, documentation, etc.)
  • Retry handler with configurable retry logic
  • Consistent error codes and status codes
  • ~93% test coverage

For detailed information, see the error handling documentation.

Context Assembly Module (Coming Soon)

The Context Assembly Module will serve as the bridge between the Knowledge and Repositories modules, providing comprehensive contextual information for LLM prompts and responses.

Key features:

  • Multi-source retrieval from documentation and repositories
  • Relevance ranking based on user queries
  • Context window optimization for LLMs
  • Source attribution and confidence indicators

For detailed information, see the context assembly documentation.

Recommended Servers

Crypto Price & Market Analysis MCP Server

Crypto Price & Market Analysis MCP Server

A Model Context Protocol (MCP) server that provides comprehensive cryptocurrency analysis using the CoinCap API. This server offers real-time price data, market analysis, and historical trends through an easy-to-use interface.

Featured
TypeScript
MCP PubMed Search

MCP PubMed Search

Server to search PubMed (PubMed is a free, online database that allows users to search for biomedical and life sciences literature). I have created on a day MCP came out but was on vacation, I saw someone post similar server in your DB, but figured to post mine.

Featured
Python
dbt Semantic Layer MCP Server

dbt Semantic Layer MCP Server

A server that enables querying the dbt Semantic Layer through natural language conversations with Claude Desktop and other AI assistants, allowing users to discover metrics, create queries, analyze data, and visualize results.

Featured
TypeScript
mixpanel

mixpanel

Connect to your Mixpanel data. Query events, retention, and funnel data from Mixpanel analytics.

Featured
TypeScript
Sequential Thinking MCP Server

Sequential Thinking MCP Server

This server facilitates structured problem-solving by breaking down complex issues into sequential steps, supporting revisions, and enabling multiple solution paths through full MCP integration.

Featured
Python
Nefino MCP Server

Nefino MCP Server

Provides large language models with access to news and information about renewable energy projects in Germany, allowing filtering by location, topic (solar, wind, hydrogen), and date range.

Official
Python
Vectorize

Vectorize

Vectorize MCP server for advanced retrieval, Private Deep Research, Anything-to-Markdown file extraction and text chunking.

Official
JavaScript
Mathematica Documentation MCP server

Mathematica Documentation MCP server

A server that provides access to Mathematica documentation through FastMCP, enabling users to retrieve function documentation and list package symbols from Wolfram Mathematica.

Local
Python
kb-mcp-server

kb-mcp-server

An MCP server aimed to be portable, local, easy and convenient to support semantic/graph based retrieval of txtai "all in one" embeddings database. Any txtai embeddings db in tar.gz form can be loaded

Local
Python
Research MCP Server

Research MCP Server

The server functions as an MCP server to interact with Notion for retrieving and creating survey data, integrating with the Claude Desktop Client for conducting and reviewing surveys.

Local
Python