Boilerplate MCP Server

- 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/<project>/ 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

- Node.js (>=20.x): Download
- Git: For version control

npm install

- TRANSPORT_MODE: Transport mode (stdio | http, default: stdio)
- PORT: HTTP server port (default: 3000)
- DEBUG: Enable debug logging (true | false, default: false)
- NODE_ENV: Node environment (development | production, default: development)

- IPAPI_API_TOKEN: API token for ip-api.com extended data (optional, free tier available)

CLI Commands:

npm run cli -- get-ip-details                                            # Get current public IP (TOON format)

npm run cli -- get-ip-details 8.8.8.8                                    # Get details for specific IP

npm run cli -- get-ip-details 1.1.1.1 -e                                 # Short form with extended data

npm run cli -- get-ip-details 1.1.1.1 --include-extended-data           # Long form with extended data

npm run cli -- get-ip-details 8.8.8.8 --no-use-https                    # Force HTTP (for free tier)

npm run cli -- get-ip-details 8.8.8.8 -o json                            # JSON output (short form)

npm run cli -- get-ip-details 8.8.8.8 --output-format json              # JSON output (long form)

npm run cli -- get-ip-details 8.8.8.8 --jq "{ip: query, country: country}"  # JMESPath filtered output

MCP Tools:
- ip_get_details - IP geolocation lookup for AI assistants
- ip_get_details_link - Same lookup + resource link output for resource-aware clients

Both tools share the same parameters:
- ipAddress (optional): IP address to lookup (omit for current device's public IP)
- includeExtendedData (optional, default: false): Include ASN, host, organization data (requires API token)
- useHttps (optional, default: true): Use HTTPS for API calls
- jq (optional): JMESPath expression to filter/transform response
- outputFormat (optional, default: "toon"): Output format - "toon" or "json"

Output behavior:
- ip_get_details: returns one text content block
- ip_get_details_link: returns the same first text block plus a resource_link block (ip://<resolved-ip>)

MCP Resources:
- ip://{ipAddress} - IP details resource template (e.g., ip://8.8.8.8, ip://1.1.1.1)
- Returns IP geolocation data in Markdown format
- Uses TOON format by default for token efficiency