Bitso MCP Server

# Bitso MCP Server An MCP server for the Bitso API that provides tools to access withdrawals and fundings data. Built with TypeScript, featuring comprehensive testing, dual transport support, and production-ready best practices. ## Features 🏦 **Bitso API Integration** - Complete Withdrawals API support (list, get by ID, get by multiple IDs, get by origin IDs) - Complete Fundings API support (list, get by ID) - Proper authentication with API key/secret and HMAC signature - Support for all API filtering and pagination parameters 🚀 **Production Ready** - Dual transport support (stdio for Claude Desktop, HTTP for development) - Comprehensive error handling and logging - Type-safe configuration with Zod validation - Project-root-aware file logging system 🧪 **Comprehensive Testing** - Two-tier testing strategy (unit + integration tests) - Real MCP protocol testing (not mocked functions) - MSW for consistent API mocking - High test coverage with Vitest 🛠️ **Developer Experience** - Hot reloading with TypeScript watch mode - Tool generation script - ESM support with proper module resolution - CI/CD pipeline with GitHub Actions 📦 **Best Practices** - Modular tool organization - Zod schema validation for all inputs - Structured logging with file output - Caching with configurable TTL ## Quick Start ### 1. Setup ```bash npm install ``` ### 2. Configure Environment ```bash cp .env.example .env # Edit .env with your Bitso API credentials ``` Required environment variables: - `BITSO_API_KEY`: Your Bitso API key - `BITSO_API_SECRET`: Your Bitso API secret ### 3. Build and Test ```bash # Build the project npm run build # Run tests npm run test # Start development server (HTTP mode) npm run start:http ``` ### 4. Add to Claude Desktop Add to your Claude Desktop configuration (`claude_desktop_config.json`): ```json { "mcpServers": { "bitso-mcp-server": { "command": "node", "args": ["/path/to/bitso-mcp-server/dist/src/index.js"], "env": { "BITSO_API_KEY": "your-bitso-api-key", "BITSO_API_SECRET": "your-bitso-api-secret" } } } } ``` ## Available Tools The server provides 6 tools to interact with the Bitso API: ### Withdrawals Tools 1. **`list_withdrawals`** - List withdrawals with optional filtering - Parameters: `currency`, `limit`, `marker`, `method`, `origin_id`, `status`, `wid` 2. **`get_withdrawal`** - Get specific withdrawal by ID - Parameters: `wid` (required) 3. **`get_withdrawals_by_ids`** - Get multiple withdrawals by comma-separated IDs - Parameters: `wids` (required, e.g., "wid1,wid2,wid3") 4. **`get_withdrawals_by_origin_ids`** - Get withdrawals by client-supplied origin IDs - Parameters: `origin_ids` (required, e.g., "origin1,origin2,origin3") ### Fundings Tools 5. **`list_fundings`** - List fundings with optional filtering - Parameters: `limit`, `marker`, `method`, `status`, `fids` 6. **`get_funding`** - Get specific funding by ID - Parameters: `fid` (required) ## Development Guide ### Project Structure ``` src/ ├── tools/ # MCP tool implementations │ └── bitso-tools.ts # Bitso API tools ├── utils/ # Shared utilities │ └── logging.ts # Project-root-aware logging ├── client.ts # Bitso API client with authentication ├── config.ts # Environment configuration ├── types.ts # TypeScript type definitions └── index.ts # Main server entry point tests/ ├── unit/ # Fast unit tests with MSW mocking ├── integration/ # Real MCP protocol tests ├── helpers/ # Test utilities │ ├── mcp-test-helper.ts │ ├── test-server-factory.ts │ └── test-config.ts ├── mocks/ # MSW request handlers └── setup.ts # Test environment setup ``` ### Creating New Tools Use the built-in tool generator: ```bash npm run build npm run create-tool ``` Or create manually following the pattern in `src/tools/bitso-tools.ts`: ```typescript import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"; import { z } from "zod"; const MyToolSchema = z.object({ param: z.string().min(1, "Parameter is required"), }); export function registerMyTools(server: McpServer, client: BitsoApiClient): void { server.tool( "my_tool", { description: "Description of what the tool does", inputSchema: { type: "object", properties: { param: { type: "string", description: "Parameter description", }, }, required: ["param"], }, }, async (params): Promise<ToolResult> => { try { const validatedParams = MyToolSchema.parse(params); // Your tool logic here return { content: [ { type: "text", text: "Tool response" } ] }; } catch (error) { // Error handling return { content: [ { type: "text", text: `Error: ${error instanceof Error ? error.message : String(error)}` } ] }; } } ); } ``` ### Testing Strategy This template uses a **two-tier testing approach**: #### Unit Tests (`tests/unit/`) - Test business logic in isolation - Mock external APIs using MSW - Fast execution, run frequently during development - Focus on data transformations, caching, validation #### Integration Tests (`tests/integration/`) - Test through real MCP protocol - Use actual MCP server instances - Validate tool registration and MCP compliance - Ensure proper request/response formatting ```bash # Run unit tests (fast) npm run test:unit # Run integration tests (slower, full MCP protocol) npm run test:integration # Run all tests with coverage npm run test:coverage ``` ### Transport Modes #### Stdio Transport (Production) Used by Claude Desktop and other MCP clients: ```bash npm start # or node dist/src/index.js ``` #### HTTP Transport (Development) Useful for debugging and development: ```bash npm run start:http # Server available at http://localhost:3000/mcp ``` ### Logging and Debugging The template includes a sophisticated logging system: - **Debug logs**: Written to `mcp-debug.log` in project root - **Project-root-aware**: Works from both source and compiled code - **Structured logging**: JSON formatting for complex data - **Console output**: Errors also logged to stderr Check logs during development: ```bash tail -f mcp-debug.log ``` ### Configuration Management Configuration uses Zod for type-safe validation: ```typescript // src/config.ts const ConfigSchema = z.object({ apiKey: z.string().min(1, 'API_KEY environment variable is required'), apiEndpoint: z.string().url().default('https://api.example.com'), // ... other config }); ``` Environment variables are validated on startup with clear error messages. ## API Integration ### Client Pattern The template includes a robust API client pattern: ```typescript // Automatic caching const resources = await client.getResources(); // Cached for 5 minutes // Error handling try { const resource = await client.getResource(id); } catch (error) { // Errors are logged and can be handled } // Connection testing const isHealthy = await client.testConnection(); ``` ### Bitso API Authentication The server uses HMAC-SHA256 authentication required by the Bitso API: ```typescript // Authentication headers are automatically generated const authHeaders = { 'key': config.apiKey, 'signature': hmacSignature, // Generated using API secret 'nonce': timestamp }; ``` Each request is signed using: - API Secret (from environment) - HTTP method - Request path - Request body (if any) - Current timestamp as nonce ## Deployment ### Building for Production ```bash npm run build npm test ``` ### CI/CD The template includes a GitHub Actions workflow (`.github/workflows/ci.yml`): - **Unit tests**: Fast feedback on basic functionality - **Integration tests**: Full MCP protocol validation - **Coverage reporting**: Ensure code quality - **Build validation**: Verify compilation ### Environment Variables Production deployment requires: ```bash BITSO_API_KEY=your-production-api-key BITSO_API_SECRET=your-production-api-secret BITSO_API_ENDPOINT=https://api.bitso.com # Production endpoint CACHE_TTL_SECONDS=300 TIMEOUT=30000 ``` ## Best Practices ### Tool Development 1. **Always use Zod schemas** for parameter validation 2. **Return MCP-compliant responses** with `{ content: [...] }` format 3. **Handle errors gracefully** with user-friendly messages 4. **Log extensively** for debugging and monitoring 5. **Test through MCP protocol** using integration tests ### Error Handling ```typescript // Good: MCP-compliant error response return { content: [ { type: "text", text: `Error: ${error.message}` } ] }; // Bad: Throwing unhandled errors throw new Error("Something went wrong"); ``` ### Performance - Use caching for expensive API calls - Implement request timeouts - Log performance metrics - Monitor API rate limits ## Troubleshooting ### Common Issues **Tool not appearing in Claude:** 1. Check build succeeded: `npm run build` 2. Restart Claude Desktop 3. Check `mcp-debug.log` for errors 4. Verify `claude_desktop_config.json` configuration **Tests failing:** 1. Run unit tests first: `npm run test:unit` 2. Check MSW handlers match your API expectations 3. Verify integration tests use real MCP server instances **API connection issues:** 1. Verify environment variables are set 2. Test API credentials manually 3. Check network connectivity and firewalls 4. Review API endpoint URLs ### Debug Mode Enable detailed logging: ```bash DEBUG=true npm start ``` ## Contributing 1. Fork the repository 2. Create a feature branch 3. Add tests for new functionality 4. Ensure all tests pass: `npm test` 5. Build successfully: `npm run build` 6. Submit a pull request ## License MIT License. See [LICENSE](LICENSE) for details. ## Related Resources - [MCP Official Documentation](https://modelcontextprotocol.io) - [Claude Desktop Integration Guide](https://docs.anthropic.com/en/docs/build-with-claude/computer-use) - [Vitest Testing Framework](https://vitest.dev) - [Zod Schema Validation](https://zod.dev)