MCP Quick Start Server

This project is a simple quick-start example of a Model Context Protocol (MCP) server built with TypeScript and the @modelcontextprotocol/sdk. It demonstrates how to define basic tools, resources, and prompts.

Features

- Tool: add: Adds two numbers.
- Parameters: a (number), b (number)
- Returns: The sum as a string.
- Tool: fetch-chuck-jokes: Fetches a random Chuck Norris joke.
- Parameters: None
- Returns: A Chuck Norris joke as a string.
- Resource: greeting: Provides a personalized greeting.
- URI Scheme: greeting://{name}
- Example: greeting://World would provide a greeting for "World".
- Prompt: getGreetingAndJoke: Instructs an AI client to greet a user by name and then tell them a Chuck Norris joke.
- Parameter: name (string)
- Example: Invoking with name: "Narendra" will set up a conversation for the AI to greet Narendra and tell a joke.

Directory Structure

quick-start/
├── build/              # Compiled JavaScript output
├── src/                # TypeScript source files
│   ├── index.ts        # Main server setup and entry point
│   ├── tools/
│   │   └── index.ts    # Tool definitions
│   ├── resources/
│   │   └── index.ts    # Resource definitions
│   └── prompts/
│       └── index.ts    # Prompt definitions
├── .gitignore
├── package-lock.json
├── package.json
├── tsconfig.json
└── README.md           # This file

Prerequisites

- Node.js (v18.x or later recommended)
- npm (comes with Node.js)

Setup & Installation

1. Clone the repository (if you haven't already):

    git clone https://github.com/scriptstar/mcp-starter-kit-node.git
    cd mcp-starter-kit-node
    

2. Install dependencies:

    npm install

    

Building the Server

To compile the TypeScript code into JavaScript, run:

npm run build

This command executes tsc (the TypeScript compiler) according to the tsconfig.json configuration and places the output in the build/ directory. It also makes the main build file executable.

Running the Server

Once built, you can start the MCP server using:

node build/index.js

Alternatively, for production-like environments, you can use the start script:

npm start

The server will start and listen for messages on standard input (stdin) and send responses to standard output (stdout), as it uses the StdioServerTransport.

Development Workflow

For a more efficient development experience, you can use the dev script:

npm run dev

This command uses concurrently to run two processes:

1. tsc -w: Watches your TypeScript files for changes and recompiles them automatically.
2. nodemon build/index.js: Watches for changes in the build directory (where tsc outputs JavaScript) and restarts the Node.js server automatically.

This provides a live-reload-like experience during development.

Linting

This project uses ESLint with TypeScript support to maintain code quality and consistency.

- To check for linting errors:

  npm run lint

  

- To automatically fix fixable linting errors:

  npm run lint:fix

  

It's recommended to run the linter before committing code.

How It Works

This server implements the Model Context Protocol.

- src/index.ts: Initializes an McpServer instance, imports tool, resource, and prompt registration functions from their respective modules, calls these functions to register them with the server, and then connects a StdioServerTransport to handle communication.
- src/tools/index.ts: Exports a registerTools function.
- add: Takes two numbers a and b and returns their sum.
- fetch-chuck-jokes: Makes an HTTP GET request to https://api.chucknorris.io/jokes/random and returns the joke.
- src/resources/index.ts: Exports a registerResources function.
- greeting: Defines a resource template greeting://{name}. When this URI is requested, it returns a personalized greeting message.
- src/prompts/index.ts: Exports a registerPrompts function.
- getGreetingAndJoke: Defines a prompt that takes a name argument. It constructs a set of initial messages to guide an AI client. The first message (role: assistant) sets the context, and the second message (role: user) formulates the request using the provided name.

Interacting with the Server (Conceptual)

This MCP server is designed to be controlled by an MCP client (e.g., an AI assistant, a development tool). The client communicates with the server by sending JSON-RPC messages to its stdin and receiving responses from its stdout.

Here's how a client might interact with the defined capabilities:

1. Calling the add tool:
A client could send a JSON-RPC request like:

    {
      "jsonrpc": "2.0",
      "method": "callTool",
      "params": { "name": "add", "args": { "a": 5, "b": 3 } },
      "id": "request1"
    }
    

The server would respond with the result:

    {
      "jsonrpc": "2.0",
      "result": { "content": [{ "type": "text", "text": "8" }] },
      "id": "request1"
    }
    

2. Accessing the greeting resource:
A client could request to read the resource URI greeting://Alice:

    {
      "jsonrpc": "2.0",
      "method": "readResource",
      "params": { "uri": "greeting://Alice" },
      "id": "request2"
    }
    

The server would respond:

    {
      "jsonrpc": "2.0",
      "result": {
        "contents": [{ "uri": "greeting://Alice", "text": "Hello, Alice!" }]
      },
      "id": "request2"
    }
    

3. Using the getGreetingAndJoke prompt:
A client wanting to initiate this guided task for "Bob" would send:

    {

      "jsonrpc": "2.0",

      "method": "getPrompt",

      "params": {

        "uri": "prompt://getGreetingAndJoke",

        "args": { "name": "Bob" }

      },

      "id": "request3"

    }

    

The server would respond with the initial messages:

    {

      "jsonrpc": "2.0",

      "result": {

        "messages": [

          {

            "role": "assistant",

            "content": {

              "type": "text",

              "text": "You are a friendly assistant. Your task is to greet the user by their name and then tell them a Chuck Norris joke. You should use the available tools and resources to accomplish this. I will now wait for your instruction to proceed with greeting and joke telling for the specified user."

            }

          },

          {

            "role": "user",

            "content": {

              "type": "text",

              "text": "Please greet Bob and then tell a Chuck Norris joke."

            }

          }

        ]

      },

      "id": "request3"

    }

    

The AI client would then process these messages and subsequently decide to call the greeting resource (for "Bob") and the fetch-chuck-jokes tool, using separate readResource and callTool requests.

Further Development

- Add more complex tools with various input/output types.
- Implement resources that interact with local files or databases.
- Create more sophisticated prompts for multi-turn conversations.
- Explore other transport layers (e.g., HTTP) if needed.
- Add comprehensive error handling and logging.

This README should give a good overview of your project!