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:

Alternative: Using npx (recommended)

For easier setup without local installation:

Note: Replace

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

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

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:

Project Structure

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:

Or set the log level in your configuration:

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

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