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:
Make the server executable:
Usage
Running the Server
The server can be run directly:
Testing with the Client
Run the test client to see the server in action:
Using with Cursor
Copy the configuration from
mcp_config.json
to your Cursor settingsUpdate the path to point to your local copy of this repository
Option 1: Using absolute path
Option 2: Using working directory (recommended)
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
Example JSON-RPC Communication
Request:
Response:
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.json
has the correct pathRestart Cursor: MCP configuration changes require a restart
Test server: Run
node server.js
to verify it starts without errorsCheck 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 install
to ensure all packages are installedPort conflicts: MCP uses stdio, so no port conflicts possible
Testing Your Server
Project Structure
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!
This server cannot be installed
local-only server
The server can only run on the client's local machine because it depends on local resources.
A simple learning-focused MCP server that demonstrates basic functionality with tools for mathematical operations, system information, and email validation, plus sample file resources. Perfect for understanding MCP protocol basics and testing integrations.