Test MCP Server
A simple MCP (Model Context Protocol) server for learning purposes. This server demonstrates basic MCP functionality including tools and resources with Zod validation.
What is MCP?
MCP (Model Context Protocol) is a protocol that allows AI models to interact with external tools and resources. It provides a standardized way for AI assistants to:
- Call tools (functions) to perform actions
- Read resources (files, data sources) to get information
- Provide structured responses with proper error handling
How MCP Works
- AI Model (like Cursor) wants to use a tool
- AI Model sends a JSON-RPC request to the MCP Server via stdio
- MCP Server processes the request and returns a response
- AI Model uses the response to help the user
The communication happens through JSON-RPC 2.0 over stdio - no web servers needed!
Features
This test server includes:
Tools (with Zod Validation)
echo: Echo back input text with validationadd_numbers: Add two numbers together with type checkingget_system_info: Get basic system information (Node.js platform details)validate_email: Validate email addresses using Zod's built-in email validation
Resources
file://example.txt: A sample text file with timestampfile://example.json: A sample JSON file with server metadata
Key Features
- ✅ Zod Validation: Runtime type checking for all tool inputs
- ✅ Error Handling: Clear error messages for invalid inputs
- ✅ JSON-RPC 2.0: Standard protocol communication
- ✅ Type Safety: TypeScript/JavaScript with proper schemas
- ✅ Resource Management: Both text and JSON resource examples
Setup
- Install dependencies:
npm install
- Make the server executable:
chmod +x server.js
Usage
Running the Server
The server can be run directly:
npm start
# or
node server.js
Testing with the Client
Run the test client to see the server in action:
npm test
# or
node test_client.js
Using with Cursor
- Copy the configuration from
mcp_config.jsonto your Cursor settings - Update the path to point to your local copy of this repository
Option 1: Using absolute path
{
"mcpServers": {
"test-server": {
"command": "node",
"args": ["/path/to/your/mcp-test/server.js"],
"env": {}
}
}
}
Option 2: Using working directory (recommended)
{
"mcpServers": {
"test-server": {
"command": "node",
"args": ["server.js"],
"cwd": "/path/to/your/mcp-test",
"env": {}
}
}
}
The mcp_config.json file in this repository serves as a template - copy it to your ~/.cursor/mcp.json and update the paths as needed.
How It Works
Server Architecture
- Server Initialization: Creates MCP server with capabilities
- Tool Registration: Tools are registered with Zod schemas for validation
- Resource Registration: Resources are registered with URIs and metadata
- Request Handling: Server processes JSON-RPC requests via stdio
- Response Generation: Responses are formatted according to MCP protocol
Communication Flow
Cursor → JSON-RPC Request → MCP Server → Zod Validation → Tool Execution → Response → Cursor
Example JSON-RPC Communication
Request:
{
"jsonrpc": "2.0",
"id": "1",
"method": "tools/call",
"params": {
"name": "add_numbers",
"arguments": {"a": 5, "b": 3}
}
}
Response:
{
"result": {
"content": [{"type": "text", "text": "Result: 5 + 3 = 8"}]
},
"jsonrpc": "2.0",
"id": "1"
}
Extending the Server
Adding New Tools
-
Define Zod Schema:
const MyToolInputSchema = z.object({ param1: z.string().describe('Description'), param2: z.number().optional() }); -
Add Tool Definition:
{ name: 'my_tool', description: 'My new tool', inputSchema: { /* JSON schema */ } } -
Implement Handler:
case 'my_tool': { const validatedArgs = MyToolInputSchema.parse(args); // Tool logic here return { content: [{ type: 'text', text: 'Result' }] }; }
Adding New Resources
-
Add Resource Definition:
{ uri: 'file://my-resource', name: 'My Resource', description: 'Description', mimeType: 'text/plain' } -
Implement Handler:
case 'file://my-resource': { return { contents: [{ type: 'text', text: 'Resource content', uri: 'file://my-resource' }] }; }
Troubleshooting
MCP Tools Not Appearing in Cursor
- Check configuration: Ensure
~/.cursor/mcp.jsonhas the correct path - Restart Cursor: MCP configuration changes require a restart
- Test server: Run
node server.jsto verify it starts without errors - Check logs: Look for error messages in Cursor's developer console
Common Issues
- Path issues: Use absolute paths in MCP configuration
- Permission errors: Ensure the server file is executable (
chmod +x server.js) - Dependency issues: Run
npm installto ensure all packages are installed - Port conflicts: MCP uses stdio, so no port conflicts possible
Testing Your Server
# Test server directly
node server.js
# Test with a simple client
echo '{"jsonrpc":"2.0","id":"1","method":"tools/list","params":{}}' | node server.js
Project Structure
mcp-test/
├── server.js # Main MCP server
├── package.json # Dependencies and scripts
├── mcp_config.json # MCP configuration template
├── README.md # This file
└── .gitignore # Git ignore rules
Contributing
- Fork the repository
- Create a feature branch
- Add your tools/resources
- Test thoroughly
- Submit a pull request
License
MIT License - feel free to use this as a starting point for your own MCP servers!
