Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 3dd383c

Browse files
arvinxxarvinxx
committed
✨ style: improve output
1 parent 5027304 commit 3dd383c

File tree

3 files changed

+372
-130
lines changed

3 files changed

+372
-130
lines changed

‎README.md‎

Lines changed: 165 additions & 129 deletions
Original file line numberDiff line numberDiff line change
@@ -1,169 +1,205 @@
1-
# Hello World MCP Server (for Testing)
1+
# MCP Hello World - MCP Server Mock for Testing
22

3-
A simple Model Context Protocol (MCP) server implementation built with TypeScript. **This server is primarily intended for testing and demonstrating basic MCP functionality.** It includes support for resources, prompts, and tools.
3+
[![][npm-release-shield]][npm-release-link]
4+
[![][npm-downloads-shield]][npm-downloads-link]
5+
[![][github-action-test-shield]][github-action-test-link]
6+
[![][github-action-release-shield]][github-action-release-link]
47

5-
## Features
8+
[github-action-release-link]: https://github.com/lobehub/mcp-hello-world/actions/workflows/release.yml
9+
[github-action-release-shield]: https://img.shields.io/github/actions/workflow/status/lobehub/mcp-hello-world/release.yml?label=Release&logo=githubactions&logoColor=white&style=flat-square
10+
[github-action-test-link]: https://github.com/lobehub/mcp-hello-world/actions/workflows/test.yml
11+
[github-action-test-shield]: https://img.shields.io/github/actions/workflow/status/lobehub/mcp-hello-world/test.yml?label=Test&logo=githubactions&logoColor=white&style=flat-square
12+
[npm-downloads-link]: https://www.npmjs.com/package/mcp-hello-world
13+
[npm-downloads-shield]: https://img.shields.io/npm/dt/mcp-hello-world?label=Downloads&logo=npm&style=flat-square
14+
[npm-release-link]: https://www.npmjs.com/package/mcp-hello-world
15+
[npm-release-shield]: https://img.shields.io/npm/v/mcp-hello-world?logo=npm&style=flat-square
616

7-
- SSE and STDIO transport support
8-
- Resource handling with static and dynamic resources
9-
- Sample prompt implementation
10-
- Example tool that echoes messages
11-
- Debug tool for server introspection
17+
This is a **minimal Model Context Protocol (MCP) server** implemented in TypeScript, primarily intended to serve as a **Test Double / Mock Server**.
1218

13-
## Getting Started
19+
**Core Purpose**: To provide a lightweight, controllable, and predictable MCP server environment for **unit testing** or **integration testing** client code that needs to interact with an MCP server.
1420

15-
### Prerequisites
21+
**Note:** This project is **not suitable for production environments** or deployment as a general-purpose MCP server.
1622

17-
- Node.js (v22 or higher)
18-
- npm or yarn
23+
## Why Use `mcp-hello-world` in Tests?
1924

20-
### Installation
25+
When testing code related to MCP clients, you usually don't want to depend on a real, potentially complex, and unpredictably responsive AI backend service. Using `mcp-hello-world` as a test double offers several advantages:
2126

22-
```bash
23-
npm install
24-
```
27+
1. **Isolation**: Focus your tests on client logic without worrying about network issues or the availability of the real server.
28+
2. **Predictability**: The provided `echo` and `debug` tools have simple, fixed behaviors, making it easy to write assertions.
29+
3. **Speed**: Fast startup and response times, suitable for frequent use in unit tests.
30+
4. **Lightweight**: Few dependencies, easy to integrate into test environments.
31+
5. **Protocol Coverage**: Supports both `STDIO` and `HTTP/SSE` MCP transport protocols, allowing you to test client behavior under different connection methods.
2532

26-
### Build
33+
## Installation
34+
35+
Add this package as a **dev dependency** to your project:
2736

2837
```bash
29-
npm run build
38+
# Using pnpm
39+
pnpm add --save-dev mcp-hello-world
40+
41+
# Or using bun
42+
bun add --dev mcp-hello-world
3043
```
3144

32-
## Running the Server
45+
## Manual Execution (for Debugging Tests)
3346

34-
There are multiple ways to run the server:
47+
You might want to run the server manually sometimes to debug your tests or client behavior.
3548

36-
### Using npx (Recommended for quick testing)
49+
### STDIO Mode
3750

38-
After building the project (`npm run build`), you can run the server directly using `npx` in STDIO mode:
51+
This is the simplest way to run, especially during local development and debugging.
3952

4053
```bash
41-
# Ensure the package is built and either published or linked locally
54+
# Ensure it's installed (globally or in the project)
55+
# Using npx (universal)
4256
npx mcp-hello-world
43-
```
4457

45-
### HTTP/SSE Transport (Web Browsers)
58+
# Or using pnpm dlx
59+
pnpm dlx mcp-hello-world
4660

47-
```bash
48-
npm run start:http
61+
# Or using bunx
62+
bunx mcp-hello-world
4963
```
5064

51-
This starts the server on http://localhost:3000 with:
52-
- SSE endpoint at `/sse`
53-
- Message endpoint at `/messages`
65+
The server will listen on standard input and output MCP responses to standard output. You can use tools like [MCP Inspector](https://github.com/lobehub/mcp-inspector) to connect to the process.
66+
67+
### HTTP/SSE Mode
5468

55-
### STDIO Transport (Command Line)
69+
If you need to debug via a network interface or test HTTP-based MCP clients.
5670

5771
```bash
58-
npm run start
59-
# or directly after building:
60-
# node build/stdio.js
72+
# 1. Clone the repository (if not already installed in the project)
73+
# git clone https://github.com/lobehub/mcp-hello-world.git
74+
# cd mcp-hello-world
75+
# pnpm install / bun install
76+
77+
# 2. Build the project
78+
# Using pnpm
79+
pnpm build
80+
# Or using bun
81+
bun run build
82+
83+
# 3. Start the HTTP server
84+
# Using pnpm
85+
pnpm start:http
86+
# Or using bun
87+
bun run start:http
6188
```
6289

63-
This runs the server in stdio mode for command-line integrations.
64-
65-
## Testing the Server
66-
67-
### Testing with cURL (HTTP Mode)
68-
69-
1. Start the HTTP server:
70-
```bash
71-
npm run start:http
72-
```
73-
74-
2. In a terminal window, connect to the SSE endpoint to get the Session ID:
75-
```bash
76-
curl -N http://localhost:3000/sse
77-
```
78-
You should see a response like:
79-
```
80-
event: endpoint
81-
data: /messages?sessionId=YOUR_SESSION_ID
82-
```
83-
**(Copy the actual `YOUR_SESSION_ID` value for the next steps)**
84-
85-
3. In another terminal window, send a request to invoke the echo tool (replace `YOUR_SESSION_ID`):
86-
```bash
87-
SESSION_ID="PASTE_YOUR_SESSION_ID_HERE"
88-
89-
curl -X POST \
90-
"http://localhost:3000/messages?sessionId=${SESSION_ID}" \
91-
-H 'Content-Type: application/json' \
92-
-d '{
93-
"jsonrpc": "2.0",
94-
"id": 1,
95-
"method": "tools/invoke",
96-
"params": {
97-
"name": "echo",
98-
"parameters": {
99-
"message": "Testing the MCP server!"
100-
}
101-
}
102-
}'
103-
```
104-
105-
4. You should see a response in the first (SSE) terminal window:
106-
```
107-
event: message
108-
data: {"jsonrpc":"2.0","id":1,"result":{"content":[{"type":"text","text":"Hello Testing the MCP server!"}]}}
109-
```
110-
111-
5. Try the debug tool (replace `YOUR_SESSION_ID`):
112-
```bash
113-
curl -X POST \
114-
"http://localhost:3000/messages?sessionId=${SESSION_ID}" \
115-
-H 'Content-Type: application/json' \
116-
-d '{
117-
"jsonrpc": "2.0",
118-
"id": 2,
119-
"method": "tools/invoke",
120-
"params": {
121-
"name": "debug",
122-
"parameters": {}
123-
}
124-
}'
125-
```
126-
(Check the SSE terminal for the list of available methods)
127-
128-
### Testing with MCP Inspector
129-
130-
For a visual interface, you can use the [MCP Inspector](https://github.com/lobehub/mcp-inspector) tool:
131-
132-
1. **HTTP Mode:** Start the server with `npm run start:http` and connect to `http://localhost:3000/sse` in the MCP Inspector.
133-
2. **STDIO Mode:** Run the server with `npm run start` or `npx mcp-hello-world` (after build/link) and connect using the STDIO transport option in the MCP Inspector.
134-
3. Browse available resources and tools.
135-
4. Invoke tools interactively.
136-
137-
*(Note: Screenshot URLs might need updating if they are placeholders or incorrect)*
138-
![MCP Inspector HTTP Mode](https://github.com/user/repo/raw/main/screenshots/mcp-inspector-http.png)
139-
![MCP Inspector STDIO Mode](https://github.com/user/repo/raw/main/screenshots/mcp-inspector-stdio.png)
140-
141-
142-
## Server API
143-
144-
Based on the implementation in `src/server.ts`:
90+
The server will start on `http://localhost:3000` and provide:
91+
- SSE endpoint: `/sse`
92+
- Message endpoint: `/messages`
93+
94+
## Usage in Tests
95+
96+
You can programmatically start and stop the `mcp-hello-world` server within your test framework (like Jest, Vitest, Mocha, etc.) for automated testing.
97+
98+
### Example: Testing with STDIO Mode (Node.js)
99+
100+
```typescript
101+
// test/my-mcp-client.test.ts (Example using Jest)
102+
import { spawn } from 'child_process';
103+
import { MCPClient } from '../src/my-mcp-client'; // Assuming this is your client code
104+
105+
describe('My MCP Client (STDIO)', () => {
106+
let mcpServerProcess;
107+
let client: MCPClient;
108+
109+
beforeAll(() => {
110+
// Start the mcp-hello-world process before tests
111+
// Using npx (or pnpm dlx / bunx) ensures the command is found and executed
112+
mcpServerProcess = spawn('npx', ['mcp-hello-world']);
113+
114+
// Instantiate your client and connect to the subprocess's stdio
115+
client = new MCPClient(mcpServerProcess.stdin, mcpServerProcess.stdout);
116+
});
117+
118+
afterAll(() => {
119+
// Shut down the mcp-hello-world process after tests
120+
mcpServerProcess.kill();
121+
});
122+
123+
it('should receive echo response', async () => {
124+
const request = {
125+
jsonrpc: '2.0',
126+
id: 1,
127+
method: 'tools/invoke',
128+
params: { name: 'echo', parameters: { message: 'test message' } },
129+
};
130+
131+
const response = await client.sendRequest(request); // Assuming your client has this method
132+
133+
expect(response).toEqual({
134+
jsonrpc: '2.0',
135+
id: 1,
136+
result: { content: [{ type: 'text', text: 'Hello test message' }] },
137+
});
138+
});
139+
140+
it('should get greeting resource', async () => {
141+
const request = {
142+
jsonrpc: '2.0',
143+
id: 2,
144+
method: 'resources/get',
145+
params: { uri: 'greeting://Alice' },
146+
};
147+
const response = await client.sendRequest(request);
148+
expect(response).toEqual({
149+
jsonrpc: '2.0',
150+
id: 2,
151+
result: { data: 'Hello Alice!' }, // Confirm return format based on actual implementation
152+
});
153+
});
154+
155+
// ... other test cases
156+
});
157+
```
158+
159+
### Example: Testing with HTTP/SSE Mode
160+
161+
For HTTP/SSE, you might need to:
162+
1. Use `exec` or `spawn` in `beforeAll` to start `pnpm start:http` or `bun run start:http`.
163+
2. Use an HTTP client (like `axios`, `node-fetch`, or your test framework's built-in client) to connect to `http://localhost:3000/sse` and `/messages` for testing.
164+
3. Ensure you shut down the started server process in `afterAll`.
165+
166+
## Provided MCP Capabilities (for Test Assertions)
167+
168+
`mcp-hello-world` provides the following fixed capabilities for interaction and assertion in your tests:
145169

146170
### Resources
147171

148-
- `hello://world` - A static hello world resource.
149-
- `greeting://{name}` - A dynamic greeting resource that takes a name parameter.
172+
- **`hello://world`**
173+
- Description: A static Hello World resource.
174+
- Method: `resources/get`
175+
- Parameters: None
176+
- Returns: `{ data: 'Hello World!' }`
177+
- **`greeting://{name}`**
178+
- Description: A dynamic greeting resource.
179+
- Method: `resources/get`
180+
- Parameters: `name` included in the URI, e.g., `greeting://Bob`.
181+
- Returns: `{ data: 'Hello {name}!' }` (e.g., `{ data: 'Hello Bob!' }`)
150182

151183
### Tools
152184

153-
- `echo` - Echoes back a message prefixed with "Hello ". Takes a `message` parameter.
154-
- `debug` - Lists all available server methods (resources, tools, prompts). Takes no parameters.
185+
- **`echo`**
186+
- Description: Echoes the input message, prefixed with "Hello ".
187+
- Method: `tools/invoke`
188+
- Parameters: `{ name: 'echo', parameters: { message: string } }`
189+
- Returns: `{ content: [{ type: 'text', text: 'Hello {message}' }] }` (e.g., `{ content: [{ type: 'text', text: 'Hello test' }] }`)
190+
- **`debug`**
191+
- Description: Lists all available MCP method definitions on the server.
192+
- Method: `tools/invoke`
193+
- Parameters: `{ name: 'debug', parameters: {} }`
194+
- Returns: A JSON structure containing definitions for all registered resources, tools, and prompts.
155195

156196
### Prompts
157197

158-
- `helpful-assistant` - A basic helpful assistant prompt definition.
159-
160-
## Troubleshooting
161-
162-
- If you get "Headers already sent" errors in HTTP mode, ensure no middleware is interfering with response handling.
163-
- Session ID management is crucial for HTTP/SSE transport. Ensure the client sends the correct `sessionId` query parameter.
164-
- Check the server console output for detailed debugging information and potential errors.
165-
- Ensure you have run `npm run build` before attempting to run the server, especially via `npx` or direct `node` commands on built files.
166-
- For `npx mcp-hello-world` to work, the package needs to be either published to npm or linked locally using `npm link` after building. Otherwise, use `npm run start` or `node build/stdio.js`.
198+
- **`helpful-assistant`**
199+
- Description: A basic assistant prompt definition.
200+
- Method: `prompts/get`
201+
- Parameters: None
202+
- Returns: A JSON structure for the prompt with predefined `system` and `user` roles.
167203

168204
## License
169205

0 commit comments

Comments
 (0)