Stampchain MCP Server

from stampchain-io

Interact with Bitcoin Stamps data via the Stampchain API, allowing queries for stamps, collections, and blockchain information.

🔥🔥🔥✓ VerifiedFreeAdvanced setup

#automation #git

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+

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

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

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

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

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

Copy & paste — that's it

npm install

Quick Start

Prerequisites

Node.js 18+
npm or yarn

Installation

Clone the repository:

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

Install dependencies:
```
npm install
```
Build the project:
```
npm run build
```
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.

Configuration

The server can be configured through:

Configuration file (JSON format)
Environment variables
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

Troubleshooting

Common Issues

Build Errors: Ensure you have Node.js 18+ and run npm install first
Connection Issues: Check that the Stampchain API is accessible
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"
  }
}

Stampchain MCP Server

Features

Available Tools

Bitcoin Stamps

Stamp Collections

SRC-20 Tokens

Development

Scripts

Testing

Project Structure

API Reference

Tool Parameters

Response Format

Development

Test Coverage

Detailed Testing Commands

Development Workflow

Support

Changelog

v0.2.0

v0.1.0

Quick Start

Prerequisites

Installation

MCP Client Integration

Claude Desktop

Other MCP Clients

Configuration

Example Configuration File

Environment Variables

Command Line Usage

Troubleshooting

Common Issues

Debugging

License