aashari/boilerplate-mcp-server

A production-ready foundation for developing custom Model Context Protocol (MCP) servers in TypeScript. Provides a complete layered architecture pattern, working example implementation, and comprehensive developer infrastructure to connect AI assistants with external APIs and data sources.
> Latest Update (Feb 2026): Updated to MCP SDK 1.26.0 and Zod 4.3.6 with continued modern registerTool patterns and streamable HTTP improvements. See docs/MODERNIZATION.md for details.
## Features
Security First: DNS rebinding protection, localhost-only binding, secure error handling
Dual Transport Support: STDIO and Streamable HTTP transports with automatic fallback
Layered Architecture: Clean separation between CLI, tools, resources, prompts, controllers, services, and utilities
Type Safety: Full TypeScript implementation with Zod v4.3.6 schema validation
All MCP Primitives: Tools, resources, and prompts (with examples)
ResourceLink Pattern: Token-efficient resource references for large responses
TOON Output Format: Token-Oriented Object Notation for 30-60% fewer tokens than JSON
JMESPath Filtering: Extract only needed fields from responses to reduce token costs
Raw Response Logging: Automatic logging of large API responses to /tmp/mcp/ / with truncation guidance
Modern SDK: Uses MCP SDK v1.26.0 with registerTool API pattern (ready for v2 migration)
Complete IP Address Example: Tools, resources, prompts, and CLI commands for IP geolocation
Comprehensive Testing: Unit and integration tests with coverage reporting (47 tests passing)
Production Tooling: ESLint, Prettier, semantic-release, and MCP Inspector integration
Error Handling: Structured error handling with isError field and contextual logging
Security Documentation: Complete SECURITY.md with authentication implementation guides
## What is MCP?
Model Context Protocol (MCP) is an open standard for securely connecting AI systems to external tools and data sources. This boilerplate implements the MCP specification with a clean, layered architecture that can be extended to build custom MCP servers for any API or data source.
## Prerequisites
Node.js (>=20.x): Download
Git: For version control
## Quick Start
bash
# Clone the repository
git clone https://github.com/aashari/boilerplate-mcp-server.git
cd boilerplate-mcp-server
# Install dependencies
npm install
# Build the project
npm run build
# Run in different modes:
# 1. CLI Mode - Execute commands directly
npm run cli -- get-ip-details 8.8.8.8
npm run cli -- get-ip-details # Get your current IP
npm run cli -- get-ip-details 1.1.1.1 -e # With extended data
npm run cli -- get-ip-details 8.8.8.8 --jq "{ip: query, country: country}" # JMESPath filter
npm run cli -- get-ip-details 8.8.8.8 -o json # JSON output
# 2. STDIO Transport - For AI assistant integration (Claude Desktop, Cursor)
npm run mcp:stdio
# 3. HTTP Transport - For web-based integrations
npm run mcp:http
# 4. Development with MCP Inspector
npm run mcp:inspect # Auto-opens browser with debugging UI
## Transport Modes
### STDIO Transport
JSON-RPC communication via stdin/stdout
Used by Claude Desktop, Cursor AI, and other local AI assistants
Run with: TRANSPORTMODE=stdio node dist/index.js