Generic MCP Server

🚀 Generic MCP Server

A production-ready implementation of the Model Context Protocol (MCP) server, built with TypeScript and Express, designed to seamlessly connect AI agents with external APIs.

🚀 Quick Start

Installation

1. Clone the repository:

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

2. Install dependencies:

   npm install
   

3. Configure the environment:

   cp .env.example .env
   

4. Add API credentials to the .env file:

   PORT=8089
   ACCESS_TOKEN=your_movie_db_access_token
   

Run the Server

In development mode (with hot reloading):

npm run dev

In production mode:

npm run build
npm start

The server will be available at http://localhost:8089 (or the port specified in the .env file).

✨ Features

• Fully implement the MCP specification.
• Use Server-Sent Events (SSE) for real-time communication.
• Have a modular architecture for easy expansion.
• Integrate with a built-in movie database for searching people and discovering films.
• Provide a type-safe interface for API responses.
• Have comprehensive error handling.
• Include a test case client as a reference.

📦 Installation

The installation steps are included in the "Quick Start" section above.

📚 Documentation

Overview

This project demonstrates how to use the @modelcontextprotocol/sdk to implement an MCP server based on Server-Sent Events (SSE). It provides developers with a practical reference for exposing APIs to AI agents and large language models (LLMs), with a focus on movie database interactions.

Implementation details can be found in the src/mcp/tools.ts, src/mcp/prompts.ts, src/helpers/ directories and related files.

What is MCP?

The Model Context Protocol (MCP) establishes a standardized interface that enables AI models to interact with external systems securely and efficiently. It defines the following structured framework:

• Resources: Data objects that the model can access.
• Tools: Executable functions that the model can call.
• Prompts: Templates that guide the model's interaction.

This standardization simplifies the process of integrating AI capabilities into existing applications and services.

For more documentation, visit the Model Context Protocol repository.

API Reference

Endpoints

MCP Components

Resources

• greeting://welcome: A static welcome message.
• users://{userId}: A dynamic user data resource.

Tools

This server implements powerful movie database tools:

• movie_database_search_person: Search for actors, directors, and other movie professionals to obtain detailed information about their careers, biographical data, and filmography.
• movie_database_discover_films: An advanced movie discovery function that recommends films based on filtering criteria.

Prompts

The MCP defines a series of prompt templates to guide the interaction between AI agents and external systems. These prompts include:

1. System Prompt: Defines the context and goals of the entire interaction.
2. User Prompt: Specific operation instructions.
3. Response Prompt: Standardizes the result format of API calls.

Movie Database Integration

The server has a built-in access interface to a well-known movie database, supporting the following operations:

1. Search for information about movies, actors, and directors.
2. Get movie details and ratings.
3. Find movie showtimes at cinemas.
4. Manage user watchlists.

All API calls are encapsulated through a type-safe interface, simplifying the development process.

Prerequisites

• Node.js 18 or higher.
• npm or yarn package manager.

🔧 Technical Details

The implementation details of the project can be found in the src/mcp/tools.ts, src/mcp/prompts.ts, src/helpers/ directories and related files.

📄 License

MIT