substrate-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is a Rust-based MCP (Model Context Protocol) server designed to provide tools for working with Substrate-based blockchains. The project is in early development (v0.1.0) and currently contains scaffolding for future Substrate-specific functionality.

Repository Structure

substrate-mcp/
├── Cargo.toml          # Project manifest with dependencies
├── Cargo.lock          # Dependency lock file
├── LICENSE             # Project license
├── README.md           # User-facing documentation with installation/usage instructions
├── CLAUDE.md           # This file - development guidance
└── src/
    ├── main.rs         # Entry point with tokio async runtime
    └── service/        # MCP service implementation
        ├── mod.rs      # Main service with tool and prompt routing
        ├── prompts/    # MCP prompt templates
        │   ├── mod.rs                      # Prompt module registry
        │   ├── analyze_release.rs          # Release impact analysis
        │   ├── get_started.rs              # Getting started guide
        │   ├── release_comparison.rs       # Release comparison
        │   ├── scaffold_pallet.rs          # Pallet scaffolding
        │   ├── security_review.rs          # Security review (merged from multiple security prompts)
        │   └── common.rs                   # Common prompt utilities
        ├── resources/  # MCP resources (documentation, references)
        ├── tools/      # MCP tools implementation
        └── utils.rs    # Service utilities

## Development Commands

### Build
```bash
cargo build

Run

cargo run

Test

cargo test

Lint and Format

cargo clippy
cargo fmt

Dependencies

• rmcp (v0.3.0): MCP server framework with transport-io feature
• tokio (v1): Async runtime with full features
• serde (v1): Serialization/deserialization with derive feature
• serde_json (v1): JSON support
• anyhow (v1): Error handling
• handlebars (v6): Template engine for prompt generation

Architecture

Core Structure

• src/main.rs: Entry point that initializes the MCP server with stdin/stdout transport using tokio async runtime
• src/service/mod.rs: Implements SubstrateService with MCP tool and prompt routing using the rmcp crate

MCP Server Pattern

This server follows the standard MCP communication pattern:

• Uses stdin/stdout for transport (tokio's stdin/stdout)
• Tools are defined using the #[tool] macro from rmcp
• Prompts are defined as SubstratePromptDefinition structs with Handlebars templates
• Server handler implemented via #[tool_handler] macro
• Tool routing via #[tool_router] macro
• Prompt routing via handle_list_prompts and handle_get_prompt functions

Current State

The server currently has:

• Basic MCP server infrastructure set up
• Multiple functional tools for blockchain interaction:
  • fetch_and_analyze_release: Fetches and analyzes Polkadot SDK releases (downloads PRDocs and generates summaries)
  • subxt_execute: Execute subxt commands for blockchain exploration
  • filter_metadata: Filter and search chain metadata
  • query_extrinsics: Query extrinsics from blocks
  • query_events: Query events from blocks
  • query_storage: Query chain storage entries
  • list_pallet_storage: List storage entries in a pallet
  • submit_dev_extrinsic: Submit extrinsics using dev accounts
• Current prompt templates for Substrate development:
  • release_comparison: Compare changes between Polkadot SDK versions
  • analyze_release: Analyze how releases impact your project
  • scaffold_pallet: Generate pallet implementation scaffolding
  • security_review: Comprehensive security review covering code security, economic threats, and performance analysis
  • get_started: Get started guide for Substrate/Polkadot development
• Server info indicating it's for Substrate-based blockchain development
• Tools, resources, and prompts capabilities enabled
• Server name: "substrate-mcp" (version 0.1.0)

Prompt System Architecture

The server uses a modular prompt template system built with Handlebars:

Prompt Structure

Each prompt module follows this pattern:

use handlebars::Handlebars;
use rmcp::model::{PromptMessage, PromptMessageRole};
use schemars::JsonSchema;
use serde::{Deserialize, Serialize};
use serde_json::json;