Skill: mcp-server-builder

# Skill: mcp-server-builder

Use mcp-server-builder to create, test, and export MCP server configurations through the REST API.

---

## Base URL

```
http://localhost:4300
```

Dashboard at `http://localhost:4301`.

---

## Server CRUD

### List servers

```bash
curl http://localhost:4300/api/servers
```

Response:
```json
[
  {
    "id": "mcp_abc123",
    "name": "File System Tools",
    "description": "Read, write, and list files",
    "version": "1.2.0",
    "transport": "stdio",
    "tool_count": 6,
    "resource_count": 2,
    "created_at": "2024-01-10T09:00:00Z",
    "updated_at": "2024-01-15T14:22:00Z"
  }
]
```

### Create a server

```bash
curl -X POST http://localhost:4300/api/servers \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Weather Tools",
    "description": "Fetch weather data for any location",
    "version": "1.0.0",
    "transport": "stdio"
  }'
```

Transport options: `stdio`, `sse`, `http`.

### Update a server

```bash
curl -X PUT http://localhost:4300/api/servers/mcp_abc123 \
  -H "Content-Type: application/json" \
  -d '{"version": "1.3.0"}'
```

### Delete a server

```bash
curl -X DELETE http://localhost:4300/api/servers/mcp_abc123
```

---

## Tool Management

### List tools for a server

```bash
curl http://localhost:4300/api/servers/mcp_abc123/tools
```

### Add a tool (mock implementation)

```bash
curl -X POST http://localhost:4300/api/servers/mcp_abc123/tools \
  -H "Content-Type: application/json" \
  -d '{
    "name": "get_weather",
    "description": "Get current weather for a location. Returns temperature, conditions, and humidity.",
    "input_schema": {
      "type": "object",
      "properties": {
        "location": {
          "type": "string",
          "description": "City name or coordinates"
        },
        "units": {
          "type": "string",
          "description": "celsius or fahrenheit"
        }
      },
      "required": ["location"]
    },
    "implementation": "mock",
    "mock_response": {
      "temperature": 22,
      "units": "celsius",
      "conditions": "Partly cloudy",
      "humidity": 65,
      "location": "San Francisco, CA"
    }
  }'
```

Tool names must be `snake_case`. Tool names with spaces or camelCase are rejected.

### Add a tool (custom code)

```bash
curl -X POST http://localhost:4300/api/servers/mcp_abc123/tools \
  -H "Content-Type: application/json" \
  -d '{
    "name": "calculate_bmi",
    "description": "Calculate body mass index from weight and height",
    "input_schema": {
      "type": "object",
      "properties": {
        "weight_kg": { "type": "number", "description": "Weight in kilograms" },
        "height_m": { "type": "number", "description": "Height in meters" }
      },
      "required": ["weight_kg", "height_m"]
    },
    "implementation": "custom",
    "custom_code": "const bmi = args.weight_kg / (args.height_m * args.height_m); return { bmi: Math.round(bmi * 10) / 10, category: bmi < 18.5 ? \"Underweight\" : bmi < 25 ? \"Normal\" : \"Overweight\" };"
  }'
```

Custom code restrictions: no `require()`, no Node.js builtins (`fs`, `http`, `child_process`). Available globals: `JSON`, `Math`, `Date`, `console`. The function receives `args` as the input object and must `return` a value.

### Update a tool

```bash
curl -X PUT http://localhost:4300/api/tools/tool_xyz001 \
  -H "Content-Type: application/json" \
  -d '{"mock_response": {"temperature": 18, "conditions": "Sunny"}}'
```

### Delete a tool

```bash
curl -X DELETE http://localhost:4300/api/tools/tool_xyz001
```

---

## Resource Management

### Add a resource

```bash
curl -X POST http://localhost:4300/api/servers/mcp_abc123/resources \
  -H "Content-Type: application/json" \
  -d '{
    "uri_template": "weather://forecast/{location}/{days}",
    "name": "Weather Forecast",
    "description": "Multi-day weather forecast for a location",
    "mime_type": "application/json",
    "mock_content": "{\"location\": \"San Francisco\", \"days\": [{\"date\": \"2024-01-16\", \"high\": 18, \"low\": 12}]}"
  }'
```

URI templates use RFC 6570 syntax. Parameters in `{braces}` are path variables.

---

## Live Test

### Run a test session

```bash
curl -X POST http://localhost:4300/api/servers/mcp_abc123/test \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "What is the weather in London right now?",
    "model": "claude-3-5-sonnet-20241022"
  }'
```

Response:
```json
{
  "rounds": 2,
  "tokens_in": 420,
  "tokens_out": 280,
  "duration_ms": 1840,
  "messages": [
    { "role": "user", "content": "What is the weather in London right now?" },
    {
      "role": "assistant",
      "content": null,
      "tool_calls": [
        { "id": "call_abc", "name": "get_weather", "arguments": { "location": "London" } }
      ]
    },
    {
      "role": "tool",
      "tool_call_id": "call_abc",
      "content": "{\"temperature\": 22, \"conditions\": \"Partly cloudy\"}"
    },
    {
      "role": "assistant",
      "content": "The weather in London is currently 22°C with partly cloudy skies."
    }
  ]
}
```

The test engine runs up to 10 tool-call rounds. Each LLM call has a 30-second timeout. If a tool returns an error, the error is included as a tool_result and the loop continues.

---

## Code Export

### Export as TypeScript

```bash
curl "http://localhost:4300/api/servers/mcp_abc123/export?lang=typescript" \
  -o my-server.ts
```

### Export as Python

```bash
curl "http://localhost:4300/api/servers/mcp_abc123/export?lang=python" \
  -o my_server.py
```

---

## Settings

### View settings

```bash
curl http://localhost:4300/api/settings
```

### Update settings

```bash
curl -X PATCH http://localhost:4300/api/settings \
  -H "Content-Type: application/json" \
  -d '{
    "llm_api_key": "sk-ant-api03-...",
    "llm_base_url": "https://api.anthropic.com",
    "default_model": "claude-3-5-sonnet-20241022",
    "max_rounds": 10,
    "round_timeout_s": 30
  }'
```

The `llm_api_key` is encrypted with AES-256-GCM before storage and is never returned in GET responses.

---

## API Reference

| Method | Path | Description |
|--------|------|-------------|
| GET | /api/servers | List all servers |
| POST | /api/servers | Create server |
| GET | /api/servers/:id | Get server |
| PUT | /api/servers/:id | Update server |
| DELETE | /api/servers/:id | Delete server |
| GET | /api/servers/:id/tools | List tools |
| POST | /api/servers/:id/tools | Add tool |
| GET | /api/tools/:id | Get tool |
| PUT | /api/tools/:id | Update tool |
| DELETE | /api/tools/:id | Delete tool |
| GET | /api/servers/:id/resources | List resources |
| POST | /api/servers/:id/resources | Add resource |
| GET | /api/resources/:id | Get resource |
| PUT | /api/resources/:id | Update resource |
| DELETE | /api/resources/:id | Delete resource |
| POST | /api/servers/:id/test | Run live test |
| GET | /api/servers/:id/export | Export code |
| GET | /api/settings | Get settings |
| PATCH | /api/settings | Update settings |
| GET | /health | Health check |

---

## Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| MCP_PORT | 4300 | API server port |
| MCP_DASHBOARD_PORT | 4301 | Dashboard port |
| MCP_DATA_DIR | ~/.mcp-server-builder | SQLite directory |
| MCP_ENCRYPTION_KEY | required | 32-byte hex key for AES-256-GCM |
| MCP_LOG_LEVEL | info | debug / info / warn / error |
| MCP_DEV | 0 | 1 = development mode |

`MCP_ENCRYPTION_KEY` must be exactly 64 hex characters (32 bytes). The server fails to start if it is missing or invalid.

Generate a key:
```bash
openssl rand -hex 32
```

---

## Troubleshooting

**Tool validation error**: Tool names must be `snake_case` (lowercase letters, digits, underscores only). Spaces, hyphens, and camelCase are rejected.

**Schema depth error**: Input schemas are limited to 3 levels of nesting. Flatten deeply nested schemas.

**Custom code error - require not defined**: Custom code runs in a sandboxed VM with no access to Node.js modules. Use mock implementation for external calls during testing.

**Test times out**: Each LLM round has a 30-second timeout. Increase `round_timeout_s` in settings or check your LLM API key is valid.

**Encryption key error on startup**: Ensure `MCP_ENCRYPTION_KEY` is set to exactly 64 hex characters.