ankittk/mcp-server-poc

MCP Agent Server

Model Context Protocol (MCP) server with Python backend and Go CLI client.

What is MCP Protocol

Model Context Protocol (MCP) is a standardized protocol for AI assistants to connect to external tools and data sources. It's different from simple JSON HTTP APIs in several key ways:

MCP vs Simple JSON HTTP

Simple JSON HTTP API:

POST /api/file
{
  "action": "read",
  "path": "test.txt"
}

MCP Protocol (JSON-RPC 2.0):

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "file_operations",
    "arguments": {
      "operation": "read",
      "path": "test.txt"
    }
  }
}

Key Differences

1. Standardized Structure: MCP uses JSON-RPC 2.0 with required fields (jsonrpc, id, method, params)
2. Tool Discovery: MCP servers expose available tools via tools/list method
3. Schema Validation: Each tool has defined input/output schemas
4. Error Handling: Standardized error codes and messages
5. AI Integration: Designed specifically for AI assistant tool calling

Performance & Overhead Analysis

JSON Structure Overhead

• Simple JSON: ~50 bytes payload
• MCP Protocol: ~150 bytes payload (3x larger)
• Overhead: ~100 bytes per request

Processing Overhead

• Simple JSON: Direct parameter extraction
• MCP Protocol: JSON-RPC parsing + method routing + schema validation
• Additional CPU: ~2-5ms per request

Network Performance

• Simple JSON: Single endpoint, no discovery needed
• MCP Protocol: Initial tool discovery + subsequent calls
• Latency Impact: +1 round trip for tool discovery

Real-World Impact

• Low-volume: Negligible difference (< 1ms)
• High-volume: MCP overhead becomes noticeable
• AI Integration: MCP benefits outweigh overhead

Where MCP Runs

• Transport Layer: HTTP, WebSocket, or stdio
• This Project: Uses HTTP on localhost:8081
• Production: Often runs in AI development environments (VS Code, etc.)

Request Flow: How GitHub Copilot Calls MCP Server

The following comprehensive diagram illustrates the complete flow of how GitHub Copilot's AI model processes user requests and calls your MCP server:

%% Dark-theme optimized
flowchart TD
    %% User Input
    A[User Request: Read the contents of README.md] --> B{Copilot AI Analysis}
    
    %% Initial Setup
    B --> C{Is MCP Server Running?}
    C -->|No| D[Start MCP Server: python3 mcp_server.py]
    C -->|Yes| E[Load Tool Definitions: copilot-tools.json]
    D --> E

    %% Tool Discovery
    E --> F[Discover Tools: GET /tools/list]
    F --> G[Store Schemas: mcp_file_operations, etc.]

    %% NLP and Intent
    G --> H[Natural Language Processing]
    H --> I[Intent: read file]
    I --> J[Entity: README.md]
    J --> K[Action: read operation]

    %% Tool Selection
    K --> L{Tool Selection}
    L -->|File| M[mcp_file_operations]
    L -->|Code| N[mcp_code_analysis]
    L -->|Git| O[mcp_git_operations]
    L -->|System| P[mcp_system_info]
    L -->|Web| Q[mcp_web_search]

    %% Parameter Extraction
    M --> R[Params:\noperation=read,\npath=README.md]
    N --> S[Params:\nfile=file.py,\ntype=quality]
    O --> T[Params:\noperation=status]
    P --> U[Params:\ninfo_type=all]
    Q --> V[Params:\nquery=term]

    %% Schema Validation
    R --> W[Schema Validation]
    S --> W
    T --> W
    U --> W
    V --> W

    %% JSON-RPC
    W --> X{Valid?}
    X -->|Yes| Y[Create JSON-RPC Request]
    X -->|No| Z[Ask for Clarification]
    Z --> A

    Y --> AA[POST to localhost:8081/mcp]
    AA --> BB[Payload:\njsonrpc: 2.0,\nid: 1,\nmethod: tools/call,\nparams...]

    %% MCP Server
    BB --> CC[Process Request]
    CC --> DD[Parse JSON-RPC]
    DD --> EE[Route to Handler]
    EE --> FF[Run Tool]
    FF --> GG[Read File]

    %% Response
    GG --> HH{Success?}
    HH -->|Yes| II[Return:\njsonrpc: 2.0,\nresult:\n  content: '# MCP...']
    HH -->|No| JJ[Return:\njsonrpc: 2.0,\nerror: File not found]

    II --> KK[Process Success]
    JJ --> KK
    KK --> LL[Parse Response]
    LL --> MM[Format for Chat]
    MM --> NN[Display in Chat]

    %% Feedback Loop
    NN --> OO{Satisfied?}
    OO -->|Yes| PP[Done]
    OO -->|No| QQ[Retry Tool]
    QQ --> L

    %% Complex Request
    A --> RR{Complex Request?\ne.g. analysis}
    RR -->|Yes| SS[Decompose]
    SS --> TT[List Files]
    SS --> UU[Read README]
    SS --> VV[Analyze Code]
    SS --> WW[Check Git]
    SS --> XX[Get System Info]

    TT --> YY[Run Multiple Tools]
    UU --> YY
    VV --> YY
    WW --> YY
    XX --> YY

    YY --> ZZ[Gather Results]
    ZZ --> AAA[Format Combined]
    AAA --> NN

    %% Dark Theme Styling
    classDef userNode fill:#1f3b4d,stroke:#ffffff,stroke-width:2px,color:#ffffff
    classDef copilotNode fill:#2e1a47,stroke:#ffffff,stroke-width:2px,color:#ffffff
    classDef serverNode fill:#1b5e20,stroke:#ffffff,stroke-width:2px,color:#ffffff
    classDef toolNode fill:#3e2723,stroke:#ffffff,stroke-width:2px,color:#ffffff
    classDef errorNode fill:#b71c1c,stroke:#ffffff,stroke-width:2px,color:#ffffff

    class A,NN,PP userNode
    class B,H,I,J,K,L,M,N,O,P,Q,R,S,T,U,V,W,X,Y,AA,BB,KK,LL,MM,OO,QQ,RR,SS,TT,UU,VV,WW,XX,YY,ZZ,AAA copilotNode
    class C,D,E,F,G,CC,DD,EE,FF,GG,HH,II,JJ serverNode
    class M,N,O,P,Q toolNode
    class Z,QQ errorNode

Architecture

Python server implements MCP protocol on port 8081. Go CLI connects as client via HTTP using JSON-RPC 2.0 format.

Python MCP Server

Implements tools using HTTP server on localhost:8081. Handles file operations, code analysis, Git operations, system info, and web search.

Go CLI Client

Fast command-line interface connecting to Python server. Provides interactive access to all MCP tools.

Why This Project is Different

Not Just Simple JSON HTTP

This project demonstrates MCP protocol implementation, not a basic JSON API:

1. Tool Discovery: CLI can discover available tools dynamically
2. Schema-Aware: Tools have defined input schemas and validation
3. Standardized Protocol: Uses JSON-RPC 2.0 with proper error handling
4. AI-Ready: Designed for AI assistant integration
5. Extensible: Easy to add new tools with proper schemas

Simple JSON HTTP Alternative

A basic alternative would be:

curl -X POST http://localhost:8081/api/file \
  -H "Content-Type: application/json" \
  -d '{"action": "read", "path": "test.txt"}'

But this lacks tool discovery, schema validation, and AI integration capabilities.

When to Use Each:

Use Simple JSON when:

• High-performance requirements (>1000 req/sec)
• Known API endpoints
• Minimal overhead needed

Use MCP Protocol when:

• AI assistant integration
• Dynamic tool discovery needed
• Schema validation required
• Extensible tool ecosystem

Architecture

Python server implements MCP protocol on port 8081. Go CLI connects as client via HTTP using JSON-RPC 2.0 format.

Usage

make setup
make run

Agent Examples

List Available Tools

mcp-cli tools

Fetching available tools from Python MCP server...
Available Tools (5):

1. file_operations
   Perform file operations like read, write, list, and search

2. code_analysis
   Analyze code for quality, issues, and suggestions

3. git_operations
   Perform Git operations like status, commit, push, pull

4. system_info
   Get system information like CPU, memory, disk usage

5. web_search
   Search the web for information

File Operations

mcp-cli file list .

Calling tool: file_operations
Result:
Directory listing for .:
  - go.mod
  - Makefile
  - README.md
  - internal
  - mcp-cli
  - mcp_server.py
  - go.sum
  - cmd
  - requirements.txt

Git Operations

mcp-cli git status

Calling tool: git_operations
Result:
Git error: fatal: not a git repository (or any of the parent directories): .git

System Information

mcp-cli sys all

Calling tool: system_info
Result:
System Information
CPU Cores: 8
Total Memory: 16384 MB
Disk Usage:
Filesystem      Size  Used Avail Use% Mounted on
/dev/sda1       500G  150G  350G  30% /

Code Analysis

mcp-cli analyze cmd/cli.go

Calling tool: code_analysis
Result:
Code Analysis for cmd/cli.go
Language: auto
Analysis Type: quality
Lines of Code: 245
Characters: 6542
Empty Lines: 32
Comment Lines: 0
Code Density: 87.0%

Server Status

mcp-cli status

Python MCP server is running at http://localhost:8081

Interactive Chat

mcp-cli chat

Starts interactive session with tool discovery and command parsing.

Testing

make test-all

Tests Python MCP server and Go CLI endpoints.

VS Code GitHub Copilot Agent Tools Integration

VS Code Configuration

The following configuration files have been created:

• .vscode/settings.json - VS Code settings with Copilot agent tools configuration
• .vscode/tasks.json - Build and run tasks
• .vscode/launch.json - Debug configurations
• .vscode/extensions.json - Recommended extensions
• copilot-tools.json - Copilot tools definition

Start the MCP Server

You can start the MCP server in several ways:

Option A: Using VS Code Tasks

1. Open Command Palette (Ctrl+Shift+P)
2. Type "Tasks: Run Task"
3. Select "Start MCP Server"

Option B: Using Terminal

python3 mcp_server.py

Using Debug Configuration

1. Go to Run and Debug panel (Ctrl+Shift+D)
2. Select "Debug MCP Server"
3. Click the play button

Verify Integration

Check if the server is running:

./mcp-cli status

List available tools:

./mcp-cli tools

Available Tools

1. File Operations (mcp_file_operations)

• read: Read file contents
• write: Write content to file
• list: List directory contents
• search: Search for files by pattern
• delete: Delete files or directories

2. Code Analysis (mcp_code_analysis)

• quality: Analyze code quality metrics
• security: Check for security issues
• performance: Analyze performance aspects
• style: Check coding style and conventions

3. Git Operations (mcp_git_operations)

• status: Check Git repository status
• commit: Create commits
• push: Push changes to remote
• pull: Pull changes from remote
• log: View commit history
• diff: Show differences

4. System Information (mcp_system_info)

• cpu: CPU information
• memory: Memory usage
• disk: Disk usage
• network: Network status
• all: All system information

5. Web Search (mcp_web_search)

• Search the web for information
• Configurable result count

Using with GitHub Copilot

1. Enable Agent Tools

The integration is configured to automatically enable Copilot agent tools. You can verify this in your VS Code settings:

{
    "github.copilot.agent.tools.enabled": true,
    "github.copilot.agent.tools.autoStart": true
}

2. Using Tools in Chat

In GitHub Copilot Chat, you can now use commands like:

• "Read the contents of main.go"
• "Analyze the code quality of mcp_server.py"
• "Check the Git status"
• "Get system information"
• "Search for information about MCP protocol"

3. Using Tools in Code

Copilot can now suggest and use these tools when you're coding. For example:

• When you ask to read a file, it can use the file operations tool
• When you need system information, it can use the system info tool
• When you need to analyze code, it can use the code analysis tool

Development Workflow

1. Development Mode

For development, you can use the interactive CLI:

./mcp-cli chat

This starts an interactive session where you can test all tools.

2. Debugging

Use the provided debug configurations:

• "Debug MCP Server" - Debug the Python server
• "Debug MCP CLI" - Debug the Go CLI
• "Debug MCP CLI Chat" - Debug the interactive chat

3. Testing

Test individual tools:

# Test file operations
./mcp-cli file read README.md

# Test Git operations
./mcp-cli git status

# Test system info
./mcp-cli sys all

# Test code analysis
./mcp-cli analyze mcp_server.py

Configuration Files

VS Code Settings (.vscode/settings.json)

• Configures Copilot agent tools
• Sets up Python and Go environments
• Enables automatic tool startup

Tasks (.vscode/tasks.json)

• Start/Stop MCP Server
• Build MCP CLI
• Run various CLI commands
• Check server status

Launch Configurations (.vscode/launch.json)

• Debug configurations for both Python and Go components
• Integrated terminal support
• Environment variable configuration

Copilot Tools (copilot-tools.json)

• Defines available tools for Copilot
• Specifies input schemas
• Configures server startup

Troubleshooting

Common Issues

1. Server not starting:

   • Check if port 8081 is available
   • Verify Python dependencies are installed
   • Check the terminal for error messages

2. CLI not working:

   • Ensure the CLI is built: go build -o mcp-cli ./cmd
   • Check if the server is running
   • Verify the server URL in CLI configuration

3. Copilot tools not available:

   • Restart VS Code
   • Check if GitHub Copilot extension is enabled
   • Verify the settings in .vscode/settings.json

Debug Commands

# Check server health
curl http://localhost:8081/health

# Test MCP protocol
curl -X POST http://localhost:8081/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

# Check CLI status
./mcp-cli status

Advanced Configuration

Custom Tool Development

To add new tools:

1. Add the tool to mcp_server.py in the _register_tools() method
2. Implement the tool logic in _execute_tool()
3. Update copilot-tools.json with the new tool definition
4. Add CLI commands in cmd/cli.go

Environment Variables

You can customize the behavior with environment variables:

export MCP_SERVER_URL=http://localhost:8081
export MCP_TIMEOUT=30s
export PYTHONPATH=/path/to/your/project

Custom Server Configuration

Modify mcp_server.py to:

• Change the server port
• Add authentication
• Implement custom protocols
• Add more sophisticated error handling

Security Considerations

1. File Access: The file operations tool can access any file on the system
2. System Information: The system info tool can expose sensitive system data
3. Network Access: The web search tool makes external network requests
4. Git Operations: Git operations can modify your repository

Always review and test tools before using them in production environments.

Contributing

To contribute to this integration:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request