{"id":27120822,"url":"https://github.com/techiral/mcp","last_synced_at":"2026-02-14T12:37:05.171Z","repository":{"id":286100794,"uuid":"960361523","full_name":"Techiral/mcp","owner":"Techiral","description":"🚀 OpenClient- The CLI-Based Universal AI Application Connector! An open-source Model Context Protocol (MCP) implementation that turbocharges LLMs by context provisioning standardization. Quickly connect a server of your choice with our client to boost your AI capabilities. Ideal for developers creating next-generation AI applications!","archived":false,"fork":false,"pushed_at":"2025-04-04T12:50:10.000Z","size":77,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-08-07T15:23:26.508Z","etag":null,"topics":["agent","ai","anthropic","chatbot","chatgpt","cli","copilot","developer-tools","gemini","knowledge-base","langchain","llm","llms","mcp","mcp-client","mcp-clients","model-context-protocol","open-source","openai","python"],"latest_commit_sha":null,"homepage":"https://github.com/Techiral/mcp/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Techiral.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-04-04T09:55:16.000Z","updated_at":"2025-05-09T20:45:33.000Z","dependencies_parsed_at":"2025-04-09T22:42:50.753Z","dependency_job_id":null,"html_url":"https://github.com/Techiral/mcp","commit_stats":null,"previous_names":["techiral/mcp"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Techiral/mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Techiral%2Fmcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Techiral%2Fmcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Techiral%2Fmcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Techiral%2Fmcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Techiral","download_url":"https://codeload.github.com/Techiral/mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Techiral%2Fmcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29443492,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-14T10:51:12.367Z","status":"ssl_error","status_checked_at":"2026-02-14T10:50:52.088Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent","ai","anthropic","chatbot","chatgpt","cli","copilot","developer-tools","gemini","knowledge-base","langchain","llm","llms","mcp","mcp-client","mcp-clients","model-context-protocol","open-source","openai","python"],"created_at":"2025-04-07T10:17:27.439Z","updated_at":"2026-02-14T12:37:05.163Z","avatar_url":"https://github.com/Techiral.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Model Context Protocol (MCP)\n\nMCP 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.\n\n## 🔌 Why MCP?\n\nMCP helps build agents and complex workflows on top of LLMs by providing:\n- Pre-built integrations for your LLM to plug into\n- Flexibility to switch between LLM providers\n- Secure data handling best practices\n- Standardized interface for AI applications\n\n## 🏗️ Core Components\n\n```mermaid\nflowchart LR\n    A[MCP Host] --\u003e B[MCP Client]\n    B --\u003e C[Terminal]\n    B --\u003e D[Filesystem]\n    B --\u003e E[Memory]\n    C --\u003e F[Local Data]\n    D --\u003e G[Local Files]\n    E --\u003e H[Remote APIs]\n```\n\n1. **MCP Hosts**: Applications (like Claude Desktop, IDEs) that need AI context\n2. **MCP Clients**: Protocol handlers that manage server connections\n3. **MCP Servers**: Lightweight programs exposing specific capabilities:\n   - Terminal Server: Execute commands\n   - Filesystem Server: Access local files\n   - Memory Server: Persistent data storage\n4. **Data Sources**:\n   - Local: Files, databases on your machine\n   - Remote: Web APIs and cloud services\n\n## 🚀 System Overview\n\n```mermaid\nflowchart LR\n    User --\u003e Client\n    Client --\u003e AI[AI Processing]\n    Client --\u003e Terminal[Terminal]\n    Client --\u003e Filesystem[Filesystem]\n    Client --\u003e Memory[Memory]\n```\n\n**Core Components:**\n- **AI Processing**: Google Gemini + LangChain for natural language understanding\n- **Terminal Server**: Executes system commands in isolated workspace\n- **Filesystem Server**: Manages file operations\n- **Memory Server**: Stores and retrieves persistent data\n\n**Key Features:**\n- Automatic server startup as needed\n- Secure workspace isolation\n- Flexible configuration\n- Extensible architecture\n\n## 📂 File Structure\n\n```mermaid\nflowchart TD\n    A[mcp] --\u003e B[clients]\n    A --\u003e C[servers]\n    A --\u003e D[workspace]\n    \n    B --\u003e E[mcp-client]\n    E --\u003e F[main.py]\n    E --\u003e G[client.py]\n    E --\u003e H[config.json]\n    E --\u003e I[.env]\n    \n    C --\u003e J[terminal]\n    J --\u003e K[server.py]\n    \n    D --\u003e L[memory.json]\n    D --\u003e M[notes.txt]\n```\n\n**Key Files:**\n- `clients/mcp-client/main.py`: Main client entry point\n- `clients/mcp-client/langchain_mcp_client_wconfig.py`: AI integration\n- `clients/mcp-client/theailanguage_config.json`: Server configurations\n- `clients/mcp-client/.env`: Environment variables\n- `servers/terminal_server/terminal_server.py`: Terminal server\n- `workspace/memory.json`: Persistent memory storage\n- `workspace/notes.txt`: System notes\n\n**File Type Breakdown:**\n\n- **Python Files (60%)**:\n  - Core application logic and business rules\n  - Server implementations and client applications\n  - Includes both synchronous and asynchronous code\n  - Follows PEP 8 style guidelines\n\n- **JSON Files (20%)**:\n  - Configuration files for servers and services\n  - API request/response schemas\n  - Persistent data storage format\n  - Strict schema validation enforced\n\n- **Text Files (15%)**:\n  - System documentation (READMEs, guides)\n  - Developer notes and annotations\n  - Temporary data storage\n  - Plaintext logs and outputs\n\n- **Other Formats (5%)**:\n  - Environment files (.env)\n  - Git ignore patterns\n  - License information\n  - Build configuration files\n\n## 🔌 Client Components\n\n```mermaid\nflowchart TD\n    A[User Input] --\u003e B[Client]\n    B --\u003e C{Type?}\n    C --\u003e|Command| D[Terminal]\n    C --\u003e|File| E[Filesystem]\n    C --\u003e|Memory| F[Storage]\n    C --\u003e|AI| G[Gemini]\n    D --\u003e H[Response]\n    E --\u003e H\n    F --\u003e H\n    G --\u003e H\n    H --\u003e I[Output]\n```\n\n### Main Client Files:\n- `langchain_mcp_client_wconfig.py`: Main client application\n- `theailanguage_config.json`: Server configurations\n- `.env`: Environment variables\n\n**Key Features:**\n- Manages multiple MCP servers\n- Integrates Google Gemini for natural language processing\n- Handles dynamic response generation\n- Processes LangChain objects\n\n**Configuration:**\n1. **theailanguage_config.json**:\n```json\n{\n  \"mcpServers\": {\n    \"terminal_server\": {\n      \"command\": \"uv\",\n      \"args\": [\"run\", \"../../servers/terminal_server/terminal_server.py\"]\n    },\n    \"memory\": {\n      \"command\": \"npx.cmd\",\n      \"args\": [\"@modelcontextprotocol/server-memory\"],\n      \"env\": {\"MEMORY_FILE_PATH\": \"workspace/memory.json\"}\n    }\n  }\n}\n```\n\n2. **.env Setup**:\n```\nGOOGLE_API_KEY=your_api_key_here\nTHEAILANGUAGE_CONFIG=clients/mcp-client/theailanguage_config.json\n```\n\n**Setup Steps:**\n1. Create `.env` file in `clients/mcp-client/`\n2. Add required variables\n3. Restart client after changes\n\n## 🖥️ Server Components\n\n```mermaid\nclassDiagram\n    class TerminalServer {\n        +path: String\n        +run()\n        +validate() \n        +execute()\n    }\n    TerminalServer --|\u003e FastMCP\n    class FastMCP {\n        +decorate()\n        +transport()\n    }\n```\n\n### Terminal Server\n- **Purpose**: Executes system commands in isolated workspace\n- **Key Features**:\n  - Fast command execution\n  - Secure workspace isolation\n  - Comprehensive logging\n- **Technical Details**:\n  - Uses `FastMCP` for transport\n  - Validates commands before execution\n  - Captures and returns output\n\n### Workspace Files\n\n#### `memory.json`\n- **Purpose**: Persistent data storage\n- **Operations**:\n  - Store/update/read data\n  - Query specific information\n- **Example Structure**:\n```json\n{\n  \"user_preferences\": {\n    \"favorite_color\": \"blue\",\n    \"interests\": [\"science fiction\"]\n  },\n  \"system_state\": {\n    \"last_commands\": [\"git status\", \"ls\"]\n  }\n}\n```\n\n#### `notes.txt`\n- **Purpose**: System documentation and notes\n- **Content Types**:\n  - User documentation (40%)\n  - System notes (30%)\n  - Temporary data (20%)\n  - Other (10%)\n\n## 🛠️ Local Setup Guide\n\n### Prerequisites\n- Python 3.9+\n- Node.js 16+\n- Google API Key\n- UV Package Manager\n\n### Installation Steps\n1. **Clone the repository**:\n   ```bash\n   git clone https://github.com/Techiral/mcp.git\n   cd mcp\n   ```\n\n2. **Set up Python environment**:\n   ```bash\n   python -m venv venv\n   # Linux/Mac:\n   source venv/bin/activate\n   # Windows:\n   venv\\Scripts\\activate\n   pip install -r requirements.txt\n   ```\n\n3. **Configure environment variables**:\n   ```bash\n   echo \"GOOGLE_API_KEY=your_key_here\" \u003e clients/mcp-client/.env\n   echo \"THEAILANGUAGE_CONFIG=clients/mcp-client/theailanguage_config.json\" \u003e\u003e clients/mcp-client/.env\n   ```\n\n4. **Install Node.js servers**:\n   ```bash\n   npm install -g @modelcontextprotocol/server-memory @modelcontextprotocol/server-filesystem\n   ```\n\n**Verification Checklist**:\n- [x] Repository cloned\n- [x] Python virtual environment created and activated\n- [x] Python dependencies installed\n- [x] .env file configured\n- [x] Node.js servers installed\n\n## 🚀 Usage Instructions\n\n### Basic Usage\n1. Start the client:\n```bash\npython clients/mcp-client/langchain_mcp_client_wconfig.py\n```\n\n2. Type natural language requests and receive responses\n\n### Command Examples\n\n**File Operations**:\n```bash\nCreate a file named example.txt\nSearch for \"function\" in all Python files\nCount lines in main.py\n```\n\n**Web Content**:\n```bash\nSummarize https://example.com\nExtract headlines from news site\n```\n\n**System Commands**:\n```bash\nList files in current directory\nCheck Python version\nRun git status\n```\n\n**Memory Operations**:\n```bash\nRemember my favorite color is blue\nWhat preferences did I set?\nShow recent commands\n```\n\n## Server Configuration\n\n**Key Configuration Files**:\n- `theailanguage_config.json`: Main server configurations\n- `.env`: Environment variables\n\n**Example Server Configs**:\n```json\n{\n  \"terminal_server\": {\n    \"command\": \"uv\",\n    \"args\": [\"run\", \"servers/terminal_server/terminal_server.py\"]\n  },\n  \"memory\": {\n    \"command\": \"npx.cmd\",\n    \"args\": [\"@modelcontextprotocol/server-memory\"],\n    \"env\": {\"MEMORY_FILE_PATH\": \"workspace/memory.json\"}\n  }\n}\n```\n\n**Configuration Tips**:\n- Use absolute paths for reliability\n- Set environment variables for sensitive data\n- Restart servers after configuration changes\n\n## 🛠️ Troubleshooting\n\n**Common Issues \u0026 Solutions**:\n\n1. **Authentication Problems**:\n   - Verify Google API key in `.env`\n   - Check key has proper permissions\n   - Regenerate key if needed\n\n2. **File Operations Failing**:\n   ```bash\n   # Check permissions\n   ls -la workspace/\n   \n   # Restart filesystem server\n   npx @modelcontextprotocol/inspector uvx mcp-server-filesystem\n   ```\n\n3. **Memory Operations Failing**:\n   ```bash\n   # Verify memory.json exists\n   ls workspace/memory.json\n   \n   # Restart memory server\n   npx @modelcontextprotocol/server-memory\n   ```\n\n**Debugging Tools**:\n- Enable verbose logging:\n  ```bash\n  echo \"LOG_LEVEL=DEBUG\" \u003e\u003e clients/mcp-client/.env\n  ```\n- List running servers:\n  ```bash\n  npx @modelcontextprotocol/inspector list\n  ```\n\n**Support**:\n- [Documentation](https://github.com/modelcontextprotocol/mcp/wiki)\n- [Report Issues](https://github.com/modelcontextprotocol/mcp/issues)\n\n## 🤝 How to Contribute\n\n**Getting Started**:\n1. Fork and clone the repository\n2. Set up development environment (see Local Setup Guide)\n\n**Development Workflow**:\n```bash\n# Create feature branch\ngit checkout -b feature/your-feature\n\n# Make changes following:\n# - Python: PEP 8 style\n# - JavaScript: StandardJS style\n# - Document all new functions\n\n# Run tests\npython -m pytest tests/\n\n# Push changes\ngit push origin feature/your-feature\n```\n\n**Pull Requests**:\n- Reference related issues\n- Describe changes clearly\n- Include test results\n- Squash commits before merging\n\n**Code Review**:\n- Reviews typically within 48 hours\n- Address all feedback before merging\n\n**Recommended Setup**:\n- VSCode with Python/JS extensions\n- Docker for testing\n- Pre-commit hooks\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftechiral%2Fmcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftechiral%2Fmcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftechiral%2Fmcp/lists"}