MCP Master

MCP Master Skill

Overview

Complete MCP (Model Context Protocol) knowledge base covering protocol principles, server development, Hermes integration, and troubleshooting. Companion project at C:/Users/FengQ/mcp-skill/.

When to Use

• User asks "what is MCP" or "how to use MCP"
• Need to create a new MCP server
• Configure Hermes to connect MCP servers
• MCP connection issues
• Evaluate MCP ecosystem and tools

MCP Core Reference

Protocol

MCP = JSON-RPC 2.0 over stdio/HTTP

4 Primitives:
- Tools:     AI calls external capabilities (actions)
- Resources: AI reads context data (read-only)
- Prompts:   Get preset prompt templates
- Sampling:  Server requests AI generation (reverse call)

Connection Lifecycle

1. Client sends initialize → Server returns capabilities
2. Client sends initialized notification
3. Client calls tools/list → Server returns tool list
4. Client calls tools/call repeatedly → Server returns results
5. Disconnect

Hermes Naming Convention

mcp_{server_name}_{tool_name}

Examples:
  mcp_filesystem_read_file
  mcp_content_writer_generate_article
  mcp_knowledge_base_kb_search

Hermes Configuration

Location: ~/.hermes/config.yaml

Stdio Server (most common)

mcp_servers:
  my_server:
    command: "python"
    args: ["path/to/server.py"]
    env:
      API_KEY: "sk-xxx"
    timeout: 120
    connect_timeout: 60

HTTP Server

mcp_servers:
  remote_server:
    url: "https://mcp.example.com/mcp"
    headers:
      Authorization: "Bearer token"

Recommended Full Config

mcp_servers:
  # From this project
  content_writer:
    command: "python"
    args: ["C:/Users/FengQ/mcp-skill/servers/mcp-content-writer/server.py"]

  knowledge_base:
    command: "python"
    args: ["C:/Users/FengQ/mcp-skill/servers/mcp-knowledge-base/server.py"]
    env:
      MCP_KB_PATH: "C:/Users/FengQ/.hermes/knowledge_base.json"

  research:
    command: "python"
    args: ["C:/Users/FengQ/mcp-skill/servers/mcp-research/server.py"]

MCP Server Development Quickstart

Minimal Server Structure

# 1. Define tools (name + description + schema + handler)
TOOLS = [{
    "name": "my_tool",
    "description": "What this tool does - AI uses this to decide when to call",
    "inputSchema": {
        "type": "object",
        "properties": {
            "param": {"type": "string", "description": "Parameter description"}
        },
        "required": ["param"]
    }
}]

# 2. Implement handler
def handle_my_tool(args):
    result = do_something(args["param"])
    return {"content": [{"type": "text", "text": result}]}

# 3. MCP protocol handler (see templates/mcp-server-template.py)

Design Principles

1. One tool, one job - Fine-grained over monolithic
2. Description is documentation - AI uses it to decide when to call
3. Schema is constraints - Types, required params, defaults all in schema
4. Error-friendly - Return "why failed + how to fix", not raw error codes

Troubleshooting

Manual Testing

# Test MCP server manually
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | python server.py

echo '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' | python server.py

Project Resources

Checklist

• Understand 4 MCP primitives (Tools/Resources/Prompts/Sampling)
• Can configure MCP servers in Hermes
• Can create a simple MCP server
• Can troubleshoot basic connection issues
• Know the MCP ecosystem landscape