Content
# Minimal MCP Server
This is the simplest implementation example of the Model Context Protocol (MCP). It provides functionality to return "Hello MCP World!" with just one file. It's a perfect first step to understand MCP.
## Author's Note
The documentation and code for this project are primarily created using AI. Therefore, the completeness of the content cannot be guaranteed. Please understand that it is under the MIT License and use it at your own risk. Additionally, this document is basically intended for those who want to implement MCP in a local environment using TypeScript.
## What is MCP?
The Model Context Protocol (MCP) is a standardized protocol for providing context information to large language model (LLM) applications. This minimal implementation demonstrates the most basic functionality to respond to tool calls from an LLM.
## Project Structure
This project is the ultimate minimal configuration, consisting of just three files:
- `index.ts` - Implementation of the MCP server (44 lines of code)
- `package.json` - Definition of dependencies
- `tsconfig.json` - TypeScript configuration
## Prerequisites
You need to have Node.js (v18 or higher) and npm installed.
*Note: The operating environment has only been verified on Windows 11.*
## Installation and Execution
You can install and run it using the following methods:
### Method 1: Run Directly
```bash
# Install dependencies
npm install
# Build TypeScript
npm run build
# Start the server
npm start
```
### Method 2: Use npx
#### Run without Global Installation
```bash
# First, build is required
npm install
npm run build
# Directly specify the built JavaScript file to run
npx node ./dist/index.js
```
#### Link the Package and Run
```bash
# Install dependencies and build
npm install
npm run build
# Link the package
npm link
# Run (can be done from anywhere)
npx minimal-mcp-server
```
### Configuration Method for Claude Desktop or cline
Set up the `claude_desktop_config.json` file as follows:
```json
{
"mcpServers": {
"hello_world": {
"command": "node", // It's better to specify the absolute path if not in the environment variable
"args": [
"absolute_path\\hello_world\\dist\\index.js"
]
}
}
}
```
Example of using npx
```bash
# Pre-install dependencies and build
npm install
npm run build
```
```json
{
"mcpServers": {
"hello_world": {
"command": "npx",
"args": [
"-y",
"absolute_path\\hello_world"
]
}
}
}
```
Set up the `cline_mcp_settings.json` file as follows:
(I tried to do it with npx, but I couldn't get it to work...)
```json
{
"mcpServers": {
"hello_world": {
"command": "node", // It's better to specify the absolute path if not in the environment variable
"args": [
"absolute_path\\hello_world\\dist\\index.js"
]
}
}
}
```
Example of specifying the absolute path for node: adjust it to your environment.
`"C:\\Users\\{Username}\\AppData\\Local\\nvm\\v22.14.0\\node.exe"`
**Note**: Replace the path with the actual project directory. On Windows, either escape the backslash (`\`) or use a forward slash (`/`).
## Code Explanation
Main components of the `index.ts` file:
1. **Tool Definition**: Defines a single tool named "hello_world"
2. **Server Instance**: Creates an MCP server using the `McpServer` class
3. **Request Handler**: Sets up a handler to respond to tool listings and calls
4. **Server Startup**: Starts the server using Stdio transport
## How to Use from the Client
Clients can communicate using the MCP protocol as follows:
1. Connect to the server
2. Retrieve the list of tools using the `tools/list` method
3. Call the "hello_world" tool using the `tools/call` method
4. Receive a response of "Hello MCP World!"
This is the minimal configuration of the MCP server. With just 44 lines of code, you can build a server that enables communication with LLMs. Let's take the first step into the fascinating world of MCP!
## Note on SDK Version
This project uses `@modelcontextprotocol/sdk` version 1.6.1. Please pay attention to the following points regarding the SDK version:
1. **Import Path**: It is important to use the correct import path. For example:
```typescript
// Correct import path (including extension)
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
```
2. **Capabilities Setting**: When initializing the MCP server, both `resources` and `tools` must be specified as capabilities:
```typescript
const server = new McpServer(
{
name: "minimal-mcp-server",
version: "1.0.0",
},
{
capabilities: {
tools: {}, // Tool capabilities
resources: {}, // Resource capabilities (required)
},
}
);
```
3. **Caution for Windows Environment**: In a Windows environment, avoid using Unix-specific commands (like `chmod`) in the scripts of package.json. Instead, set it up as follows:
```json
"scripts": {
"build": "tsc",
"start": "node dist/index.js"
}
```
4. **TypeScript Configuration**: Properly setting the module resolution in `tsconfig.json` can help avoid import issues:
```json
"compilerOptions": {
"moduleResolution": "NodeNext",
// Other settings...
}
```
## Troubleshooting
### Common Issues and Solutions
1. **Import Errors**: If you see an error like `Cannot find module '@modelcontextprotocol/sdk/...'`:
- Check if you are using the correct import path (including the `.js` extension)
- Verify the module settings in `tsconfig.json`
- Ensure that dependencies are correctly installed
2. **Connection Errors**: If you cannot connect to the server:
- Ensure the server is running
- Check if you are using the correct transport settings
- Verify firewall and permission settings
3. **Type Errors**: If there are TypeScript compilation errors:
- Adding `skipLibCheck: true` to tsconfig.json may help
- Check the TypeScript version for compatibility with the SDK
## Next Steps
Once you understand this minimal implementation, try expanding it as follows:
1. Add tools that accept parameters
2. Implement multiple tools
3. Add resource capabilities
4. Implement HTTP transport
For more detailed information and implementation examples, refer to the documentation in the `docs` folder.
## MCP Related Resources
- [Model Context Protocol Official Documentation](https://modelcontextprotocol.io)
- [MCP Project](https://github.com/modelcontextprotocol)
- [MCP Reference Implementation](https://github.com/modelcontextprotocol/typescript-sdk)
## Reference Articles
- [Using MCP (Filesystem) with Claude for Desktop (Windows version)! The most detailed steps explained in Japanese](https://qiita.com/amatatsuk/items/4303f6bedd441c8a2588)
## Disclaimer
This project utilizes the following external libraries.
* **@modelcontextprotocol/sdk:** [https://github.com/modelcontextprotocol/typescript-sdk](https://github.com/modelcontextprotocol/typescript-sdk) (MIT License)
* **@types/node:** (MIT License)
* **typescript:** [https://github.com/microsoft/TypeScript](https://github.com/microsoft/TypeScript) (Apache License 2.0)
These libraries are provided under their respective licenses. Please adhere to the terms of use for each library.
This project does not guarantee the functionality of these external libraries.
