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