mcpserver.so LogoMCPFly
Submit
Model Context Protocol (MCP) logo

Model Context Protocol (MCP)

by Techiral

AI/Protocols & CommunicationProtocolContextIntegrationAgents

MCP is an open protocol that standardizes how applications provide context to LLMs, enabling seamless connection between AI models and various data sources/tools. It's like USB-C for AI applications.

View on GitHub

Last updated: N/A

Model Context Protocol (MCP)

MCP is an open protocol that standardizes how applications provide context to LLMs - think of it like USB-C for AI applications. It enables seamless connection between AI models and various data sources/tools.

🔌 Why MCP?

MCP helps build agents and complex workflows on top of LLMs by providing:

  • Pre-built integrations for your LLM to plug into
  • Flexibility to switch between LLM providers
  • Secure data handling best practices
  • Standardized interface for AI applications

🏗️ Core Components

flowchart LR
    A[MCP Host] --> B[MCP Client]
    B --> C[Terminal]
    B --> D[Filesystem]
    B --> E[Memory]
    C --> F[Local Data]
    D --> G[Local Files]
    E --> H[Remote APIs]
  1. MCP Hosts: Applications (like Claude Desktop, IDEs) that need AI context
  2. MCP Clients: Protocol handlers that manage server connections
  3. MCP Servers: Lightweight programs exposing specific capabilities:
    • Terminal Server: Execute commands
    • Filesystem Server: Access local files
    • Memory Server: Persistent data storage
  4. Data Sources:
    • Local: Files, databases on your machine
    • Remote: Web APIs and cloud services

🚀 System Overview

flowchart LR
    User --> Client
    Client --> AI[AI Processing]
    Client --> Terminal[Terminal]
    Client --> Filesystem[Filesystem]
    Client --> Memory[Memory]

Core Components:

  • AI Processing: Google Gemini + LangChain for natural language understanding
  • Terminal Server: Executes system commands in isolated workspace
  • Filesystem Server: Manages file operations
  • Memory Server: Stores and retrieves persistent data

Key Features:

  • Automatic server startup as needed
  • Secure workspace isolation
  • Flexible configuration
  • Extensible architecture

📂 File Structure

flowchart TD
    A[mcp] --> B[clients]
    A --> C[servers]
    A --> D[workspace]
    
    B --> E[mcp-client]
    E --> F[main.py]
    E --> G[client.py]
    E --> H[config.json]
    E --> I[.env]
    
    C --> J[terminal]
    J --> K[server.py]
    
    D --> L[memory.json]
    D --> M[notes.txt]

Key Files:

  • clients/mcp-client/main.py: Main client entry point
  • clients/mcp-client/langchain_mcp_client_wconfig.py: AI integration
  • clients/mcp-client/theailanguage_config.json: Server configurations
  • clients/mcp-client/.env: Environment variables
  • servers/terminal_server/terminal_server.py: Terminal server
  • workspace/memory.json: Persistent memory storage
  • workspace/notes.txt: System notes

File Type Breakdown:

  • Python Files (60%):

    • Core application logic and business rules
    • Server implementations and client applications
    • Includes both synchronous and asynchronous code
    • Follows PEP 8 style guidelines

  • JSON Files (20%):

    • Configuration files for servers and services
    • API request/response schemas
    • Persistent data storage format
    • Strict schema validation enforced

  • Text Files (15%):

    • System documentation (READMEs, guides)
    • Developer notes and annotations
    • Temporary data storage
    • Plaintext logs and outputs

  • Other Formats (5%):

    • Environment files (.env)
    • Git ignore patterns
    • License information
    • Build configuration files

🔌 Client Components

flowchart TD
    A[User Input] --> B[Client]
    B --> C{Type?}
    C -->|Command| D[Terminal]
    C -->|File| E[Filesystem]
    C -->|Memory| F[Storage]
    C -->|AI| G[Gemini]
    D --> H[Response]
    E --> H
    F --> H
    G --> H
    H --> I[Output]

Main Client Files:

  • langchain_mcp_client_wconfig.py: Main client application
  • theailanguage_config.json: Server configurations
  • .env: Environment variables

Key Features:

  • Manages multiple MCP servers
  • Integrates Google Gemini for natural language processing
  • Handles dynamic response generation
  • Processes LangChain objects

Configuration:

  1. theailanguage_config.json:
{
  "mcpServers": {
    "terminal_server": {
      "command": "uv",
      "args": ["run", "../../servers/terminal_server/terminal_server.py"]
    },
    "memory": {
      "command": "npx.cmd",
      "args": ["@modelcontextprotocol/server-memory"],
      "env": {"MEMORY_FILE_PATH": "workspace/memory.json"}
    }
  }
}
  1. .env Setup:
GOOGLE_API_KEY=your_api_key_here
THEAILANGUAGE_CONFIG=clients/mcp-client/theailanguage_config.json

Setup Steps:

  1. Create .env file in clients/mcp-client/
  2. Add required variables
  3. Restart client after changes

🖥️ Server Components

classDiagram
    class TerminalServer {
        +path: String
        +run()
        +validate() 
        +execute()
    }
    TerminalServer --|> FastMCP
    class FastMCP {
        +decorate()
        +transport()
    }

Terminal Server

  • Purpose: Executes system commands in isolated workspace
  • Key Features:
    • Fast command execution
    • Secure workspace isolation
    • Comprehensive logging
  • Technical Details:
    • Uses FastMCP for transport
    • Validates commands before execution
    • Captures and returns output

Workspace Files

memory.json
  • Purpose: Persistent data storage
  • Operations:
    • Store/update/read data
    • Query specific information
  • Example Structure:
{
  "user_preferences": {
    "favorite_color": "blue",
    "interests": ["science fiction"]
  },
  "system_state": {
    "last_commands": ["git status", "ls"]
  }
}
notes.txt
  • Purpose: System documentation and notes
  • Content Types:
    • User documentation (40%)
    • System notes (30%)
    • Temporary data (20%)
    • Other (10%)

🛠️ Local Setup Guide

Prerequisites

  • Python 3.9+
  • Node.js 16+
  • Google API Key
  • UV Package Manager

Installation Steps

  1. Clone the repository:

    git clone https://github.com/Techiral/mcp.git
cd mcp

  2. Set up Python environment:

    python -m venv venv
# Linux/Mac:
source venv/bin/activate
# Windows:
venv\Scripts\activate
pip install -r requirements.txt

  3. Configure environment variables:

    echo "GOOGLE_API_KEY=your_key_here" > clients/mcp-client/.env
echo "THEAILANGUAGE_CONFIG=clients/mcp-client/theailanguage_config.json" >> clients/mcp-client/.env

  4. Install Node.js servers:

    npm install -g @modelcontextprotocol/server-memory @modelcontextprotocol/server-filesystem

Verification Checklist:

  • [x] Repository cloned
  • [x] Python virtual environment created and activated
  • [x] Python dependencies installed
  • [x] .env file configured
  • [x] Node.js servers installed

🚀 Usage Instructions

Basic Usage

  1. Start the client:
python clients/mcp-client/langchain_mcp_client_wconfig.py
  1. Type natural language requests and receive responses

Command Examples

File Operations:

Create a file named example.txt
Search for "function" in all Python files
Count lines in main.py

Web Content:

Summarize https://example.com
Extract headlines from news site

System Commands:

List files in current directory
Check Python version
Run git status

Memory Operations:

Remember my favorite color is blue
What preferences did I set?
Show recent commands

Server Configuration

Key Configuration Files:

  • theailanguage_config.json: Main server configurations
  • .env: Environment variables

Example Server Configs:

{
  "terminal_server": {
    "command": "uv",
    "args": ["run", "servers/terminal_server/terminal_server.py"]
  },
  "memory": {
    "command": "npx.cmd",
    "args": ["@modelcontextprotocol/server-memory"],
    "env": {"MEMORY_FILE_PATH": "workspace/memory.json"}
  }
}

Configuration Tips:

  • Use absolute paths for reliability
  • Set environment variables for sensitive data
  • Restart servers after configuration changes

🛠️ Troubleshooting

Common Issues & Solutions:

  1. Authentication Problems:

    • Verify Google API key in .env
    • Check key has proper permissions
    • Regenerate key if needed

  2. File Operations Failing:

    # Check permissions
ls -la workspace/

# Restart filesystem server
npx @modelcontextprotocol/inspector uvx mcp-server-filesystem

  3. Memory Operations Failing:

    # Verify memory.json exists
ls workspace/memory.json

# Restart memory server
npx @modelcontextprotocol/server-memory

Debugging Tools:

  • Enable verbose logging: 
    echo "LOG_LEVEL=DEBUG" >> clients/mcp-client/.env
  • List running servers: 
    npx @modelcontextprotocol/inspector list

Support:

🤝 How to Contribute

Getting Started:

  1. Fork and clone the repository
  2. Set up development environment (see Local Setup Guide)

Development Workflow:

# Create feature branch
git checkout -b feature/your-feature

# Make changes following:
# - Python: PEP 8 style
# - JavaScript: StandardJS style
# - Document all new functions

# Run tests
python -m pytest tests/

# Push changes
git push origin feature/your-feature

Pull Requests:

  • Reference related issues
  • Describe changes clearly
  • Include test results
  • Squash commits before merging

Code Review:

  • Reviews typically within 48 hours
  • Address all feedback before merging

Recommended Setup:

  • VSCode with Python/JS extensions
  • Docker for testing
  • Pre-commit hooks