Stampchain MCP Server

A Model Context Protocol (MCP) server for interacting with Bitcoin Stamps and SRC-20 token data via the Stampchain API. This server provides MCP-compatible clients with tools to query Bitcoin Stamps, collections, and SRC-20 tokens.

Features

• Bitcoin Stamps Tools: Get stamp details, search stamps, and retrieve recent stamps
• Stamp Collections: Query collections and search through collection data
• SRC-20 Tokens: Get 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"]
    }
  }
}

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

Development

Scripts

• npm run dev - Start development server with hot reload
• npm run build - Build the TypeScript project
• npm run test - Run all tests
• npm run test:watch - Run tests in watch mode
• npm run test:coverage - Run tests with coverage report
• npm run typecheck - TypeScript type checking
• npm run format - Format code with Prettier
• npm run validate - Full validation suite

Testing

The project includes comprehensive test coverage:

# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Run in watch mode during development
npm run test:watch

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

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"
  }
}

Development

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)

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

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/new-feature
3. Make your changes
4. Run tests: npm test
5. Commit your changes: git commit -am 'Add new feature'
6. Push to the branch: git push origin feature/new-feature
7. Submit a pull request

Code Style

• Use TypeScript for all new code
• Follow TypeScript strict mode guidelines
• Write tests for new features
• Update documentation as needed
• Run npm run validate before submitting PRs

License

MIT License - see 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 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 schema validation improvements

v0.1.0

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