Skip to main content
Glama

Test MCP Server

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

  1. AI Model (like Cursor) wants to use a tool
  2. AI Model sends a JSON-RPC request to the MCP Server via stdio
  3. MCP Server processes the request and returns a response
  4. 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

  1. Install dependencies:
npm install
  1. 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

  1. Copy the configuration from mcp_config.json to your Cursor settings
  2. 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

  1. Server Initialization: Creates MCP server with capabilities
  2. Tool Registration: Tools are registered with Zod schemas for validation
  3. Resource Registration: Resources are registered with URIs and metadata
  4. Request Handling: Server processes JSON-RPC requests via stdio
  5. 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

  1. Define Zod Schema:
    const MyToolInputSchema = z.object({ param1: z.string().describe('Description'), param2: z.number().optional() });
  2. Add Tool Definition:
    { name: 'my_tool', description: 'My new tool', inputSchema: { /* JSON schema */ } }
  3. Implement Handler:
    case 'my_tool': { const validatedArgs = MyToolInputSchema.parse(args); // Tool logic here return { content: [{ type: 'text', text: 'Result' }] }; }

Adding New Resources

  1. Add Resource Definition:
    { uri: 'file://my-resource', name: 'My Resource', description: 'Description', mimeType: 'text/plain' }
  2. Implement Handler:
    case 'file://my-resource': { return { contents: [{ type: 'text', text: 'Resource content', uri: 'file://my-resource' }] }; }

Troubleshooting

MCP Tools Not Appearing in Cursor

  1. Check configuration: Ensure ~/.cursor/mcp.json has the correct path
  2. Restart Cursor: MCP configuration changes require a restart
  3. Test server: Run node server.js to verify it starts without errors
  4. 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

  1. Fork the repository
  2. Create a feature branch
  3. Add your tools/resources
  4. Test thoroughly
  5. Submit a pull request

License

MIT License - feel free to use this as a starting point for your own MCP servers!

-
security - not tested
F
license - not found
-
quality - not tested

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.

  1. What is MCP?
    1. How MCP Works
  2. Features
    1. Tools (with Zod Validation)
    2. Resources
    3. Key Features
  3. Setup
    1. Usage
      1. Running the Server
      2. Testing with the Client
      3. Using with Cursor
    2. How It Works
      1. Server Architecture
      2. Communication Flow
      3. Example JSON-RPC Communication
    3. Extending the Server
      1. Adding New Tools
      2. Adding New Resources
    4. Troubleshooting
      1. MCP Tools Not Appearing in Cursor
      2. Common Issues
      3. Testing Your Server
    5. Project Structure
      1. Contributing
        1. License

          MCP directory API

          We provide all the information about MCP servers via our MCP API.

          curl -X GET 'https://glama.ai/api/mcp/v1/servers/Shahzaibalikhawaja/model-context-protocols'

          If you have feedback or need assistance with the MCP directory API, please join our Discord server