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+

Related MCP server: Bybit MCP Server

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