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 validation
add_numbers: Add two numbers together with type checking
get_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 timestamp
file://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.json to 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.json has the correct path
Restart Cursor: MCP configuration changes require a restart
Test server: Run node server.js to 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 install to 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!

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 validation
add_numbers: Add two numbers together with type checking
get_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 timestamp
file://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.json to 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.json has the correct path
Restart Cursor: MCP configuration changes require a restart
Test server: Run node server.js to 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 install to 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!