Skip to main content
Glama
Test MCP Server

Test MCP Server

README.md
# 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:
```bash
npm install
```

2. Make the server executable:
```bash
chmod +x server.js
```

## Usage

### Running the Server

The server can be run directly:
```bash
npm start
# or
node server.js
```

### Testing with the Client

Run the test client to see the server in action:
```bash
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**
```json
{
  "mcpServers": {
    "test-server": {
      "command": "node",
      "args": ["/path/to/your/mcp-test/server.js"],
      "env": {}
    }
  }
}
```

**Option 2: Using working directory (recommended)**
```json
{
  "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:**
```json
{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "tools/call",
  "params": {
    "name": "add_numbers",
    "arguments": {"a": 5, "b": 3}
  }
}
```

**Response:**
```json
{
  "result": {
    "content": [{"type": "text", "text": "Result: 5 + 3 = 8"}]
  },
  "jsonrpc": "2.0",
  "id": "1"
}
```

## Extending the Server

### Adding New Tools

1. **Define Zod Schema:**
   ```javascript
   const MyToolInputSchema = z.object({
     param1: z.string().describe('Description'),
     param2: z.number().optional()
   });
   ```

2. **Add Tool Definition:**
   ```javascript
   {
     name: 'my_tool',
     description: 'My new tool',
     inputSchema: { /* JSON schema */ }
   }
   ```

3. **Implement Handler:**
   ```javascript
   case 'my_tool': {
     const validatedArgs = MyToolInputSchema.parse(args);
     // Tool logic here
     return { content: [{ type: 'text', text: 'Result' }] };
   }
   ```

### Adding New Resources

1. **Add Resource Definition:**
   ```javascript
   {
     uri: 'file://my-resource',
     name: 'My Resource',
     description: 'Description',
     mimeType: 'text/plain'
   }
   ```

2. **Implement Handler:**
   ```javascript
   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
```bash
# 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!

TDQS

B3.3/5.0

Scored across 4 tools

Disambiguation5/5

Each tool targets a completely different operation: text echo, arithmetic, system introspection, and email validation. There is no plausible way an agent could confuse one for another.

Naming Consistency4/5

Three tools follow a clear verb_noun snake_case pattern (add_numbers, get_system_info, validate_email), while 'echo' is a bare verb with no object. The single deviation is minor and still unambiguous.

Tool Count4/5

Four tools is a thin but defensible surface for a test/demo server, and each tool exercises a distinct capability. It would feel under-scoped for a real utility server, but fits the stated testing purpose.

Completeness3/5

The toolset is an arbitrary grab bag of unrelated utilities with no defined domain, so there is no lifecycle to complete. No obvious dead ends exist, but there is also no coherent surface an agent could rely on beyond these four one-off operations.

Maintenance

ActivityInactive
ResponsivenessOutdated data