Stampchain MCP

🚀 Stampchain MCP Server

A Model Context Protocol (MCP) server that enables interaction with Bitcoin Stamps and SRC - 20 token data via the Stampchain API, offering MCP - compatible clients tools for querying related data.

✨ Features

• Bitcoin Stamps Tools: Retrieve stamp details, conduct stamp searches, and fetch recent stamps.
• Stamp Collections: Query collections and search through collection data.
• SRC - 20 Tokens: Obtain token information and search through SRC - 20 tokens.
• Type - safe: Built with TypeScript and Zod validation.
• Comprehensive Testing: Full test coverage with CI validation.
• Configurable: Flexible configuration options for different environments.
• Cross - platform: Works on Ubuntu, Windows, and macOS with Node.js 18+.

🚀 Quick Start

Prerequisites

• Node.js 18+
• npm or yarn

📦 Installation

1. Clone the repository:

   git clone https://github.com/stampchain-io/stampchain-mcp.git
   cd stampchain-mcp
   

2. Install dependencies:

   npm install
   

3. Build the project:

   npm run build
   

4. Test the installation:

   npm run start
   

💻 MCP Client Integration

Claude Desktop

To use with Claude Desktop, add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "stampchain": {
      "command": "node",
      "args": ["/path/to/stampchain-mcp/dist/index.js"],
      "cwd": "/path/to/stampchain-mcp"
    }
  }
}

Alternative: Using npx (recommended) For easier setup without local installation:

{
  "mcpServers": {
    "stampchain": {
      "command": "npx",
      "args": ["-y", "stampchain-mcp"]
    }
  }
}

⚠️ Important Note

Replace /path/to/stampchain-mcp with the actual path to your installation directory.

Other MCP Clients

This server implements the standard MCP protocol and can be used with any MCP - compatible client. Refer to your client's documentation for specific configuration instructions. The server accepts connections via stdio transport.

💻 Available Tools

Bitcoin Stamps

• get_stamp: Get detailed information about a specific stamp by ID.
• search_stamps: Search stamps with various filters (creator, collection, etc.).
• get_recent_stamps: Get the most recently created stamps.

Stamp Collections

• get_collection: Get detailed information about a specific collection.
• search_collections: Search collections with filters.

SRC - 20 Tokens

• get_token_info: Get detailed information about a specific SRC - 20 token.
• search_tokens: Search SRC - 20 tokens with various filters.

📚 Configuration

The server can be configured through:

1. Configuration file (JSON format)
2. Environment variables
3. Command line arguments

Example Configuration File

{
  "api": {
    "baseUrl": "https://stampchain.io/api",
    "timeout": 30000,
    "retries": 3
  },
  "logging": {
    "level": "info"
  },
  "registry": {
    "maxTools": 1000,
    "validateOnRegister": true
  }
}

Environment Variables

• STAMPCHAIN_API_URL: API base URL (default: https://stampchain.io/api).
• STAMPCHAIN_LOG_LEVEL: Logging level (debug, info, warn, error).
• STAMPCHAIN_API_TIMEOUT: API timeout in milliseconds.

Command Line Usage

# Start with default configuration
npm run start

# Start with custom config file
npm run start -- --config config.json

# Start with debug logging
npm run start -- --log-level debug

# Show available tools
npm run tools

# Show version information
npm run version

📚 API Reference

Tool Parameters

All tools accept various parameters for filtering and pagination:

• limit: Number of results to return (default: 10, max: 100).
• page: Page number for pagination (default: 1).
• sort: Sort field and direction (e.g., "created_desc").

Response Format

All tools return structured data with:

• success: Boolean indicating if the request was successful.
• data: The requested data (stamps, collections, tokens).
• pagination: Pagination information when applicable.
• error: Error details if the request failed.

📚 Troubleshooting

Common Issues

1. Build Errors: Ensure you have Node.js 18+ and run npm install first.
2. Connection Issues: Check that the Stampchain API is accessible.
3. MCP Client Integration: Verify the path in your configuration file is correct.

Debugging

Enable debug logging to see detailed information:

npm run start -- --debug

Or set the log level in your configuration:

{
  "logging": {
    "level": "debug"
  }
}

🔧 Technical Details

Test Coverage

This project maintains comprehensive test coverage across multiple areas:

• ✅ Unit Tests: Core utilities and helper functions.
• ✅ Integration Tests: MCP server functionality.
• ✅ API Validation: Ensures v2.3 API compatibility.
• ✅ Schema Validation: TypeScript and Zod schema alignment.
• ✅ Cross - platform: Tested on Ubuntu, Windows, and macOS.
• ✅ Multi - version: Node.js 18.x, 20.x, and 22.x support.
• ✅ Real API Testing: Validates against live Stampchain API v2.3.

Detailed Testing Commands

# Run specific test suites
npm run test:unit         # Unit tests for utilities and helpers
npm run test:integration  # Integration tests for MCP server
npm run test:api         # API validation tests (v2.3 compatibility)
npm run test:tools       # Tool functionality tests
npm run test:schemas     # Schema validation tests

# Advanced testing options
npm run test:ui          # Run tests in UI mode (interactive)
npm run test:ci          # CI test run (includes coverage)
npm run validate         # Full validation (schema + typecheck + format + tests)

Project Structure

src/
├── api/           # API client and related utilities
├── config/        # Configuration management
├── interfaces/    # TypeScript interfaces
├── protocol/      # MCP protocol handlers
├── schemas/       # Zod validation schemas
├── tools/         # MCP tool implementations
├── utils/         # Utility functions
├── index.ts       # Main entry point
└── server.ts      # Server implementation

Development Workflow

1. Install dependencies: npm install
2. Start development server: npm run dev
3. Run tests in watch mode: npm run test:watch
4. Validate before commit: npm run validate

📄 License

This project is under the MIT License. See the LICENSE file for details.

📚 Support

• Issues: GitHub Issues
• Documentation: Stampchain API Docs
• Community: Telegram @BitcoinStamps

📚 Changelog

v0.2.0

• Stampchain API v2.3 Compatibility: Updated schemas and validation for the latest API.
• Enhanced Testing: Comprehensive test suite with cross - platform CI validation.
• Improved Documentation: Professional README with status badges and better organization.
• Simplified Development: Streamlined validation pipeline (TypeScript + Prettier).
• Bug Fixes: Resolved CI issues and improved schema validation.

v0.1.0

• Initial release.
• Basic Bitcoin Stamps, Collections, and SRC - 20 tools.
• MCP client integration.
• Comprehensive test suite.