antoniodevivo/mcp-server-template

MCP Server Template

A lightweight and extensible MCP (Model Context Protocol) server implementation built with Express.js and TypeScript. This template provides a solid foundation for building AI-powered applications that can communicate with MCP-compatible clients through Server-Sent Events (SSE).

Features

• Express.js server with TypeScript support
• Server-Sent Events (SSE) for real-time communication
• MCP protocol implementation
• Note management system
• Docker support
• Input validation using Zod

Prerequisites

• Node.js 22 or higher
• npm (Node Package Manager)
• Docker (optional)

Installation

1. Clone the repository:

git clone https://github.com/yourusername/mcp-template.git
cd mcp-template

2. Install dependencies:

npm install

3. Build the project:

npm run build

Running the Server

Local Development

npm start

The server will start on port 3123 by default.

Using Docker

Build the Docker image:

docker build -t mcp-template .

Run the container:

docker run -p 3123:3123 mcp-template

API Endpoints

MCP Endpoints

• GET /mcp/sse - Establishes an SSE connection for MCP communication

Available Tools

• add-note - Add a new note to the note store

  • Parameters:
    • noteTitle: string - The title of the note
    • noteContent: string - The content of the note
    • noteTags: string[] (optional) - Tags for the note

• update-note - Update an existing note

  • Parameters:
    • noteId: string - The ID of the note to update
    • noteTitle: string - The new title of the note
    • noteContent: string - The new content of the note
    • noteTags: string[] (optional) - The new tags for the note

• get-note - Retrieve a specific note

  • Parameters:
    • noteId: string - The ID of the note to retrieve

• get-all-notes - Retrieve all notes from the store

  • Parameters: None

• delete-note - Delete a note from the store

  • Parameters:
    • noteId: string - The ID of the note to delete

Input Validation

The server uses Zod for runtime type checking and input validation. All incoming requests are validated against predefined schemas before processing. This ensures type safety and data integrity throughout the application.

Environment Variables

• PORT - Server port (default: 3123)
• LOG_LEVEL - Logging level (default: "info")
• DOCKER - Set to "true" when running in Docker
• DEV - Set to "true" for development mode

Development

Project Structure

src/
├── config.ts         # Configuration settings
├── index.ts         # Application entry point
├── logger.ts        # Logging configuration
├── note-store.ts    # Note management system
└── server/
    └── routers/
        └── mcp.ts   # MCP router implementation

Building

npm run build

Linting

npm run lint

License

MIT

Author

Antonio De Vivo