https://github.com/aashari/boilerplate-mcp-server
A comprehensive TypeScript implementation of the Model Context Protocol (MCP) server with tools, resources, and prompts for LLM integration
https://github.com/aashari/boilerplate-mcp-server
boilerplate claude llm mcp model-context-protocol prompts resources sdk server tools typescript
Last synced: 8 months ago
JSON representation
A comprehensive TypeScript implementation of the Model Context Protocol (MCP) server with tools, resources, and prompts for LLM integration
- Host: GitHub
- URL: https://github.com/aashari/boilerplate-mcp-server
- Owner: aashari
- License: mit
- Created: 2025-03-12T15:52:55.000Z (8 months ago)
- Default Branch: main
- Last Pushed: 2025-03-12T17:20:04.000Z (8 months ago)
- Last Synced: 2025-03-12T17:23:05.983Z (8 months ago)
- Topics: boilerplate, claude, llm, mcp, model-context-protocol, prompts, resources, sdk, server, tools, typescript
- Language: TypeScript
- Homepage: https://modelcontextprotocol.io
- Size: 43.9 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project
- metorial-index - Boilerplate MCP Server - Develop custom Model Context Protocol (MCP) servers to connect AI systems to external APIs and data sources, enabling seamless interaction and data retrieval. The server includes built-in functionality for IP lookup and command-line interface support for enhanced integration capabilities. (APIs and HTTP Requests)
- awesome-mcp-servers - **boilerplate-mcp-server** - TypeScript Model Context Protocol (MCP) server boilerplate providing IP lookup tools/resources. Includes CLI support and extensible structure for connecting AI systems (LLMs) to external data sources like ip-api.com. Ideal template for creating new MCP integrations via Node.js. `typescript` `ai` `ai-integration` `anthropic` `boilerplate` `npm install aashari/boilerplate-mcp-server` (🤖 AI/ML)
- awesome-mcp-servers - **boilerplate-mcp-server** - TypeScript Model Context Protocol (MCP) server boilerplate providing IP lookup tools/resources. Includes CLI support and extensible structure for connecting AI systems (LLMs) to external data sources like ip-api.com. Ideal template for creating new MCP integrations via Node.js. `typescript` `ai` `ai-integration` `anthropic` `boilerplate` `npm install aashari/boilerplate-mcp-server` (🤖 AI/ML)
README
# Boilerplate MCP Server
A boilerplate Model Context Protocol (MCP) server implementation using TypeScript. This project demonstrates how to build a well-structured MCP server that exposes both tools and resources to AI applications like Claude Desktop.
## Prerequisites
- Node.js v22.14.0 or higher
- npm (comes with Node.js)
## Installation
```bash
npm install
```
## Development
To run the server in development mode with hot reloading:
```bash
npm run dev
```
To test the server with the MCP Inspector (a debugging tool for MCP servers):
```bash
npm run inspector
```
## Building
To compile the TypeScript code to JavaScript:
```bash
npm run build
```
## Running
To run the compiled JavaScript code:
```bash
npm start
```
## CI/CD with GitHub Actions
This project includes a GitHub Actions workflow for continuous integration and deployment:
### Continuous Integration & Deployment
On every push to the `main` branch:
- Checks code formatting with Prettier
- Runs ESLint to ensure code quality
- Builds the TypeScript code to verify compilation
- Publishes the package to GitHub Packages automatically
This automated workflow ensures that the latest version of your package is always available in GitHub Packages whenever changes are pushed to the main branch.
## Project Structure
The project follows a clean architecture pattern with clear separation of concerns:
- `src/index.ts` - Main entry point for the MCP server
- `src/controllers/` - Business logic layer that handles core functionality, transforms responses from services, and formats data
- `src/services/` - Data access layer that interacts with external APIs and data sources (e.g., ip-api.com)
- `src/tools/` - MCP tool definitions and parameter schemas using Zod
- `src/resources/` - MCP resource definitions that expose data like IP address details
- `src/utils/` - Shared utilities like logging
- `dist/` - Compiled JavaScript output (generated after build)
### Current Implementation
The server currently implements IP address functionality in two ways:
1. **As a Tool**: `get_ip_details`
- Defined in `src/tools/ipaddress.tool.ts`
- Accepts an optional IP address parameter
- Returns details about the specified IP or the current device
2. **As a Resource**: `Current Device IP`
- Defined in `src/resources/ipaddress.resource.ts`
- Exposes IP information as a resource at `ip://current`
- Provides details about the current device's IP address
Both implementations follow the same data flow:
1. The controller (`ipaddress.controller.ts`) handles the business logic
2. The service (`vendor.ip-api.com.service.ts`) fetches data from the external API
3. The data is formatted and returned to the client
## About MCP
The Model Context Protocol (MCP) is a standardized protocol developed by Anthropic for connecting AI applications (clients) with tools, resources, and data (servers). It enables seamless interoperability between LLM hosts and external systems, fostering a local-first, extensible AI ecosystem.
### Key Features
- **Resources**: Expose data (e.g., files, database records) for clients to use as context
- **Tools**: Executable functions that clients can call (e.g., querying a database, fetching weather data)
- **Prompts**: Reusable templates for guiding LLM interactions
- **Transport**: Supports STDIO (local process communication) and HTTP/SSE (remote communication)
### Architecture
MCP follows a client-server architecture:
- **MCP Hosts**: AI applications like Claude Desktop that need access to external data
- **MCP Clients**: Components within hosts that connect to servers
- **MCP Servers**: Lightweight programs (like this one) that expose specific capabilities through the standardized protocol
## Testing
Run tests with:
```bash
npm test
```
Generate test coverage report:
```bash
npm run test:coverage
```
## License
ISC