Hello World MCP Server

A minimal Model Context Protocol (MCP) server written in TypeScript. This project demonstrates how to create MCP-compliant resources and tools for use with LLMs and MCP-enabled clients like Claude Desktop.

Features

• MCP Resources:
  Provides simple resources at hello://greeting, hello://info, and a resource list at hello://list.

• MCP Tool:
  A helloTool that echoes messages or returns a default greeting.

• Stdio Transport:
  Communicates via standard input/output, making it easy to integrate with MCP clients.

Getting Started

Prerequisites

• Node.js (v18+ recommended)
• npm (comes with Node.js)

Installation

Install from npm (Recommended)

Install the package globally or locally:

# Global installation
npm install -g hello-world-mcp-server

# Or local installation
npm install hello-world-mcp-server

After installation, you can run the server using:

# If installed globally, you can use npx
npx hello-world-mcp-server

# Or directly with node (find the path)
node $(npm root -g)/hello-world-mcp-server/dist/index.js

# On macOS/Linux (global install):
node /usr/local/lib/node_modules/hello-world-mcp-server/dist/index.js

# On Windows (global install):
node %APPDATA%\npm\node_modules\hello-world-mcp-server\dist\index.js

# Local install:
node ./node_modules/hello-world-mcp-server/dist/index.js

Note: This MCP server communicates via stdio, so it's typically configured in MCP clients (like Claude Desktop) rather than run directly. See the "Using with Claude Desktop" section below.

Install from Source

If you want to modify the code or install from source:

git clone <repository-url>
cd mcp-hello-world-ts
npm install

Build the Project

Compile TypeScript source files to JavaScript in the dist/ directory:

npm run build

Run the Server (Standalone)

npm start

This will start the MCP server via Node.js using the built output.

Run Tests

Integration tests are provided to verify the MCP server works end-to-end:

npm test

This runs the tests in src/integration.test.ts using Jest.

Using with Claude Desktop

You can configure Claude Desktop or any MCP client to use this server as a plugin/tool by specifying the command to launch the MCP server.

Example Configuration Snippet

Using npm Package (Recommended)

If you installed the package via npm, add the following to your Claude Desktop settings:

Option 1: Using npx (Recommended - works everywhere)

"hello-world-mcp": {
  "command": "npx",
  "args": [
    "hello-world-mcp-server"
  ]
}

Option 2: Direct path (requires full path)

"hello-world-mcp": {
  "command": "node",
  "args": [
    "/usr/local/lib/node_modules/hello-world-mcp-server/dist/index.js"
  ]
}

Note: Adjust the path based on your system:

• macOS/Linux (global install): /usr/local/lib/node_modules/hello-world-mcp-server/dist/index.js
• Windows (global install): %APPDATA%\\npm\\node_modules\\hello-world-mcp-server\\dist\\index.js
• Local install: ./node_modules/hello-world-mcp-server/dist/index.js

Using Source Code

If you cloned the repository, add the following to your Claude Desktop settings:

"hello-world-mcp": {
  "command": "node",
  "args": [
    "/path/to/mcp-hello-world-ts/dist/index.js"
  ]
}

• Replace /path/to/mcp-hello-world-ts/ with the full path to where you cloned this repo.
• Make sure you have built the project (npm run build) before starting Claude Desktop.

Project Structure

.
├── src/
│   ├── index.ts                # Main MCP server entry point
│   ├── resources/helloResource.ts  # MCP resource definitions
│   └── tools/helloTool.ts      # MCP tool definition
├── dist/                       # Compiled JS output
├── package.json
├── tsconfig.json
├── README.md
└── ...

Customization

• To add new tools or resources, create new files in src/resources/ or src/tools/ and register them in src/index.ts.
• Modify helloResource.ts or helloTool.ts to change the greeting or add additional functionality.

License

MIT License

Author

• @snoopdave