{"_id":"@belastbaar/mcp-server","name":"@belastbaar/mcp-server","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@belastbaar/mcp-server","version":"1.0.0","description":"MCP server exposing Dutch tax data and knowledge base for AI assistants via the Model Context Protocol","type":"module","main":"dist/index.js","bin":{"belastbaar-mcp":"dist/index.js"},"repository":{"type":"git","url":"git+https://github.com/belastbaar/mcp-server.git"},"homepage":"https://belastbaar.com/en/developers","bugs":{"url":"https://github.com/belastbaar/mcp-server/issues"},"publishConfig":{"access":"public"},"scripts":{"build":"tsc","dev":"tsx src/index.ts","start":"node dist/index.js","start:stdio":"node dist/index.js --transport stdio","start:http":"node dist/index.js --transport http","typecheck":"tsc --noEmit","test":"node --experimental-vm-modules node_modules/jest/bin/jest.js","test:watch":"node --experimental-vm-modules node_modules/jest/bin/jest.js --watch","test:coverage":"node --experimental-vm-modules node_modules/jest/bin/jest.js --coverage"},"keywords":["mcp","model-context-protocol","dutch-tax","belastbaar","tax-data"],"author":{"name":"Belastbaar"},"license":"MIT","dependencies":{"@modelcontextprotocol/sdk":"^1.0.0","@sentry/node":"^9.34.0","express":"^5.1.0","zod":"^3.25.76"},"devDependencies":{"@types/express":"^5.0.2","@types/jest":"^29.5.14","@types/node":"^24.2.0","jest":"^29.7.0","ts-jest":"^29.3.4","tsx":"^4.20.5","typescript":"^5.9.2"},"engines":{"node":">=20.9.0"},"gitHead":"51009d9523cc4a4c6530469b3dde7ab97d0ba125","types":"./dist/index.d.ts","_id":"@belastbaar/mcp-server@1.0.0","_nodeVersion":"24.10.0","_npmVersion":"11.6.2","dist":{"integrity":"sha512-gRtV5/Jkroe0UGa7PfLEVjLFlN9lNdAbhHCQM0MiwSDr/TgBYDjmqYzadqJuRG4SDXNYjMzcAvNuL45DLfPL4A==","shasum":"790fabfe10c0861eefe6d272415d47477709449a","tarball":"https://registry.npmjs.org/@belastbaar/mcp-server/-/mcp-server-1.0.0.tgz","fileCount":37,"unpackedSize":199656,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCoTu9ppxzgJkBDbsBPlnpOiWxq9kVJAGrTrImyuEotSQIgUDzXMxkVQWHQwb4Tw1kBwUz3CInAYKesEcV/jsicibM="}]},"_npmUser":{"name":"nigeljs","email":"hello@belastbaar.com"},"directories":{},"maintainers":[{"name":"nigeljs","email":"hello@belastbaar.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mcp-server_1.0.0_1764682362013_0.3885015919698891"},"_hasShrinkwrap":false}},"time":{"created":"2025-12-02T13:32:41.927Z","1.0.0":"2025-12-02T13:32:42.194Z","modified":"2025-12-02T13:32:42.478Z"},"maintainers":[{"name":"nigeljs","email":"hello@belastbaar.com"}],"description":"MCP server exposing Dutch tax data and knowledge base for AI assistants via the Model Context Protocol","homepage":"https://belastbaar.com/en/developers","keywords":["mcp","model-context-protocol","dutch-tax","belastbaar","tax-data"],"repository":{"type":"git","url":"git+https://github.com/belastbaar/mcp-server.git"},"author":{"name":"Belastbaar"},"bugs":{"url":"https://github.com/belastbaar/mcp-server/issues"},"license":"MIT","readme":"# Belastbaar MCP Server\n\nA Model Context Protocol (MCP) server that exposes Dutch tax data and a comprehensive tax knowledge base. This server enables AI assistants like Claude, Cursor, and other MCP-compatible tools to access accurate Dutch tax information.\n\n## Features\n\n- **Tax Data Resources**: Complete Dutch tax data for 2024 and 2025\n- **Knowledge Base**: 14 comprehensive guides on Dutch tax topics\n- **Interactive Tools**: Search, compare, and look up tax rates\n- **Prompts**: Pre-built prompt templates for common tax scenarios\n- **Caching**: In-memory LRU caching for improved performance\n- **Authentication**: API key authentication for HTTP transport\n- **Rate Limiting**: Configurable rate limiting to prevent abuse\n- **Logging**: Structured JSON logging for monitoring\n- **i18n**: Dutch and English translations\n- **Docker**: Ready for containerized deployment\n\n### Tax Data Resources (2024 & 2025)\n  - Income tax brackets and rates\n  - Box 2 (substantial interest) rates\n  - Box 3 (wealth tax) constants\n  - Toeslagen (government allowances) thresholds\n  - Vehicle tax (MRB) rates\n  - Energy tax rates\n  - VAT rates\n  - Tax credits\n\n- **Knowledge Base**: Comprehensive guides on Dutch tax topics\n  - 30% ruling for expats\n  - ZZP/self-employment deductions\n  - Tax credits explained\n  - Toeslagen eligibility\n  - And more...\n\n- **Interactive Tools**:\n  - `search_knowledge`: Search the knowledge base\n  - `compare_tax_years`: Compare tax data between years\n  - `get_tax_rate`: Look up specific tax rates\n\n## Quick Start\n\n```bash\ncd mcp-server\nnpm install\nnpm run build\nnpm run start:http\n```\n\nServer will be available at `http://localhost:3100`.\n\n## Installation\n\n```bash\ncd mcp-server\nnpm install\nnpm run build\n```\n\n## Usage\n\n### stdio Transport (AI Assistants)\n\nFor use with Claude Desktop, Cursor, or other MCP-compatible AI assistants:\n\n```bash\nnpm run start:stdio\n```\n\nOr directly:\n\n```bash\nnode dist/index.js --transport stdio\n```\n\n### HTTP Transport (API Access)\n\nFor hosted deployment or programmatic access:\n\n```bash\nnpm run start:http\n```\n\nOr with a custom port:\n\n```bash\nPORT=8080 node dist/index.js --transport http\n```\n\n## Claude Desktop Configuration\n\nAdd to your `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"belastbaar\": {\n      \"command\": \"node\",\n      \"args\": [\"/path/to/belastbaar/mcp-server/dist/index.js\", \"--transport\", \"stdio\"]\n    }\n  }\n}\n```\n\n## Cursor Configuration\n\nAdd to your Cursor MCP settings:\n\n```json\n{\n  \"belastbaar-tax\": {\n    \"command\": \"node\",\n    \"args\": [\"/path/to/belastbaar/mcp-server/dist/index.js\", \"--transport\", \"stdio\"]\n  }\n}\n```\n\n## Available Resources\n\n### Tax Data Resources\n\n| URI Pattern | Description |\n|-------------|-------------|\n| `tax://YEAR/overview` | Complete tax data for the year |\n| `tax://YEAR/income-tax` | Income tax brackets, credits, deductions |\n| `tax://YEAR/box2` | Substantial interest tax rates |\n| `tax://YEAR/box3` | Wealth tax constants |\n| `tax://YEAR/toeslagen` | Government allowances |\n| `tax://YEAR/vehicle` | Motor vehicle tax (MRB) |\n| `tax://YEAR/energy` | Energy tax rates |\n| `tax://YEAR/vat` | VAT rates |\n| `tax://YEAR/credits` | Tax credits (heffingskortingen) |\n\nReplace `YEAR` with `2024` or `2025`.\n\n### Knowledge Base Resources\n\n| URI | Description |\n|-----|-------------|\n| `knowledge://overview` | List all knowledge documents |\n| `knowledge://income-tax-brackets-2025` | Income tax brackets explained |\n| `knowledge://tax-credits-general` | General tax credit guide |\n| `knowledge://labour-tax-credit` | Labour tax credit guide |\n| `knowledge://30-percent-ruling-overview` | 30% ruling for expats |\n| `knowledge://zzp-deductions` | ZZP/self-employment deductions |\n| `knowledge://box3-wealth-tax` | Box 3 wealth tax explained |\n| `knowledge://zorgtoeslag` | Healthcare allowance guide |\n| `knowledge://huurtoeslag` | Housing allowance guide |\n| `knowledge://mrb-vehicle-tax` | Motor vehicle tax guide |\n| `knowledge://energy-tax` | Energy tax explained |\n| `knowledge://vat-btw` | VAT rates guide |\n| `knowledge://box2-substantial-interest` | Box 2 tax explained |\n| `knowledge://dutch-tax-system-overview` | Dutch tax system overview |\n| `knowledge://tax-optimization-overview` | Tax optimization strategies |\n\n## HTTP API Endpoints\n\nWhen running with HTTP transport, the server provides both MCP protocol and REST API:\n\n### MCP Protocol Endpoint (for MCP clients)\n\n```\nPOST /mcp                    # MCP client-to-server communication\nGET /mcp                     # MCP server-to-client notifications (SSE)\nDELETE /mcp                  # MCP session termination\n```\n\n**Session Management**: Include `Mcp-Session-Id` header for stateful sessions.\n\n### REST API (for non-MCP clients)\n\n```\nGET /                        # Server info\nGET /health                  # Health check\nGET /api/resources           # List all resources\nGET /api/resources/tax/:year/:type  # Get tax data\nGET /api/resources/knowledge     # List knowledge documents\nGET /api/resources/knowledge/:id # Get knowledge document\nPOST /api/tools/search       # Search knowledge base\nPOST /api/tools/compare      # Compare tax years\nPOST /api/tools/rate         # Get tax rate\n```\n\n### Examples\n\n**Search knowledge base:**\n```bash\ncurl -X POST http://localhost:3100/api/tools/search \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"query\": \"30% ruling\", \"maxResults\": 3}'\n```\n\n**Get income tax data:**\n```bash\ncurl http://localhost:3100/api/resources/tax/2025/income-tax\n```\n\n**Compare tax years:**\n```bash\ncurl -X POST http://localhost:3100/api/tools/compare \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"fromYear\": 2024, \"toYear\": 2025}'\n```\n\n**Get tax rate for specific income:**\n```bash\ncurl -X POST http://localhost:3100/api/tools/rate \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"type\": \"income\", \"year\": 2025, \"income\": 50000}'\n```\n\n**With authentication:**\n```bash\ncurl http://localhost:3100/api/resources/tax/2025/income-tax \\\n  -H \"X-API-Key: your-api-key\"\n```\n\n## Available Prompts\n\nThe server provides pre-built prompt templates for common tax scenarios:\n\n| Prompt | Description |\n|--------|-------------|\n| `calculate-tax` | Calculate Dutch income tax with all deductions and credits |\n| `compare-scenarios` | Compare tax implications (e.g., employee vs ZZP) |\n| `thirty-percent-ruling` | Check 30% ruling eligibility and benefits |\n| `check-toeslagen` | Check eligibility for government allowances |\n| `zzp-optimization` | Optimize tax deductions for self-employed |\n| `explain-tax-concept` | Get detailed explanation of any Dutch tax concept |\n| `calculate-box3` | Calculate Box 3 wealth tax on savings/investments |\n\n### Using Prompts\n\nPrompts can be invoked by AI assistants to get structured guidance:\n\n```\nUser: Use the calculate-tax prompt with income=50000, year=2025, employment_type=employee\n```\n\nThe prompt will generate a comprehensive request including:\n- Tax bracket breakdown\n- All applicable credits\n- Social contributions\n- Net income calculation\n\n## Tool Examples\n\n### search_knowledge\n\nSearch the knowledge base for Dutch tax information:\n\n```json\n{\n  \"query\": \"30% ruling expat\",\n  \"maxResults\": 3,\n  \"category\": \"30-percent-ruling\"  // optional\n}\n```\n\n### compare_tax_years\n\nCompare tax data between years:\n\n```json\n{\n  \"fromYear\": 2024,\n  \"toYear\": 2025\n}\n```\n\n### get_tax_rate\n\nLook up specific tax rates:\n\n```json\n{\n  \"type\": \"income\",  // income, box2, box3, or vat\n  \"year\": 2025,      // optional, default: 2025\n  \"income\": 50000    // optional, for bracket lookup\n}\n```\n\n## Environment Variables\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `PORT` | HTTP server port | 3100 |\n| **Authentication (Optional)** | | |\n| `MCP_AUTH_ENABLED` | Enable API key authentication (must be `true` to enable) | false |\n| `MCP_API_KEYS` | Comma-separated list of valid API keys | - |\n| `MCP_API_KEY_HEADER` | Header name for API key | X-API-Key |\n| **Rate Limiting** | | |\n| `MCP_RATE_LIMIT_ENABLED` | Enable rate limiting | true |\n| `MCP_RATE_LIMIT_MAX` | Max requests per window | 100 |\n| `MCP_RATE_LIMIT_WINDOW_MS` | Rate limit window in ms | 60000 |\n| **Logging** | | |\n| `MCP_LOG_LEVEL` | Log level (debug/info/warn/error) | info |\n| `MCP_LOG_JSON` | Output logs as JSON | false |\n| `MCP_LOG_TIMESTAMP` | Include timestamps in logs | true |\n| **Sentry (Error Tracking)** | | |\n| `MCP_SENTRY_DSN` | Sentry DSN for error tracking | - |\n| `MCP_SENTRY_ENABLED` | Enable/disable Sentry (auto if DSN set) | true |\n\n### Authentication\n\nTo enable API key authentication:\n\n```bash\nMCP_AUTH_ENABLED=true \\\nMCP_API_KEYS=key1,key2,key3 \\\nnpm run start:http\n```\n\nClients must then include the API key in requests:\n\n```bash\ncurl -H \"X-API-Key: key1\" http://localhost:3100/resources/tax/2025/income-tax\n```\n\n### Rate Limiting\n\nRate limiting is enabled by default. To customize:\n\n```bash\nMCP_RATE_LIMIT_MAX=50 \\\nMCP_RATE_LIMIT_WINDOW_MS=30000 \\\nnpm run start:http\n```\n\nRate limit headers are included in responses:\n- `X-RateLimit-Limit`: Max requests per window\n- `X-RateLimit-Remaining`: Remaining requests\n- `X-RateLimit-Reset`: Unix timestamp when window resets\n\n## Internationalization (i18n)\n\nThe server supports Dutch (nl) and English (en). Language is detected from:\n1. `Accept-Language` header\n2. Defaults to English\n\nPrompts and messages are fully translated:\n\n```bash\ncurl http://localhost:3100/resources/tax/2025/income-tax \\\n  -H \"Accept-Language: nl\"\n```\n\n## Architecture\n\n```\nmcp-server/\n├── src/\n│   ├── index.ts              # CLI entry point\n│   ├── server.ts             # MCP server setup\n│   ├── transports/\n│   │   ├── stdio.ts          # stdio for AI assistants\n│   │   └── http.ts           # HTTP/REST API\n│   ├── resources/\n│   │   ├── tax-data.ts       # Tax data (2024, 2025)\n│   │   └── knowledge-base.ts # Knowledge documents\n│   ├── tools/\n│   │   ├── search-knowledge.ts\n│   │   ├── compare-years.ts\n│   │   └── get-tax-rate.ts\n│   ├── prompts/\n│   │   └── tax-prompts.ts    # Prompt templates\n│   ├── i18n/\n│   │   └── messages.ts       # Dutch/English translations\n│   ├── utils/\n│   │   ├── auth.ts           # API key authentication\n│   │   ├── cache.ts          # In-memory LRU caching\n│   │   ├── errors.ts         # Error handling\n│   │   ├── logger.ts         # Structured logging\n│   │   └── rate-limit.ts     # Rate limiting\n│   └── __tests__/            # Jest test suites\n├── Dockerfile\n├── docker-compose.yml\n├── jest.config.js\n├── package.json\n└── tsconfig.json\n```\n\n## Performance Features\n\n### Caching\n\nThe server includes in-memory LRU caching for:\n- Knowledge base search results (5 minute TTL)\n- Tax data lookups (10 minute TTL)\n\nCache is automatically managed with LRU eviction when limits are reached.\n\n### Resource Links\n\nSearch results include `resource_link` content types, allowing AI assistants to:\n- See related resources without full content\n- Selectively fetch detailed information\n- Reduce token usage\n\n## Docker Deployment\n\n### Quick Start\n\n```bash\ndocker compose up -d\n```\n\n### Build and Run\n\n```bash\n# Build image\ndocker build -t belastbaar-mcp-server .\n\n# Run container\ndocker run -p 3100:3100 \\\n  -e MCP_AUTH_ENABLED=true \\\n  -e MCP_API_KEYS=your-secret-key \\\n  belastbaar-mcp-server\n```\n\n### Environment Configuration\n\n```yaml\n# docker-compose.yml\nenvironment:\n  - MCP_AUTH_ENABLED=true\n  - MCP_API_KEYS=key1,key2\n  - MCP_RATE_LIMIT_MAX=100\n  - MCP_LOG_JSON=true\n```\n\n## Development\n\n```bash\n# Install dependencies\nnpm install\n\n# Run in development mode\nnpm run dev\n\n# Type check\nnpm run typecheck\n\n# Build for production\nnpm run build\n\n# Run tests\nnpm test\n\n# Run tests with coverage\nnpm run test:coverage\n\n# Run tests in watch mode\nnpm run test:watch\n```\n\n### Testing\n\nThe server includes comprehensive test suites:\n\n```bash\nnpm test\n\n# Output:\n# PASS src/__tests__/utils/cache.test.ts\n# PASS src/__tests__/utils/errors.test.ts\n# PASS src/__tests__/utils/auth.test.ts\n# PASS src/__tests__/utils/rate-limit.test.ts\n# PASS src/__tests__/i18n/messages.test.ts\n#\n# Test Suites: 5 passed, 5 total\n# Tests:       106 passed, 106 total\n```\n\n## License\n\nMIT\n\n## Related\n\n- [Belastbaar](https://belastbaar.com) - Dutch Tax Calculator Platform\n- [Model Context Protocol](https://modelcontextprotocol.io) - MCP Specification\n","readmeFilename":"README.md","_rev":"1-16c192d73ae08477b19581edfce35daf"}