{"id":"03d13f9a-815c-4d22-aadd-0fc68affa167","slug":"mcp-ghost","kind":"mcp","name":"mcp-ghost","summary":"MCP server for Claude Code that surfaces Ghostty shell integration events","owner":"kimjune01","repoUrl":"https://github.com/kimjune01/mcp-ghost","license":"MIT","licenseTier":"permissive","trust":"community","stars":3,"match":null,"fewStars":true,"format":"mcp","createdAt":"2025-05-25T19:52:44.000Z","addedAt":"2026-10-21T15:16:06.280Z","logoUrl":"https://avatars.githubusercontent.com/u/6355623?u=5fae89354d5d89846512f55efa1100756aea820c&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["developer-tools","cloud-infra"],"tags":[],"runtime":"python","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-27T00:05:29.925Z","sample":false,"url":"https://conduits.dev/tools/mcp-ghost","language":"Python","transports":["stdio"],"install":{"pypi":"mcp-ghost"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# MCP-Ghost 👻\n\n**Intelligent MCP tool orchestration library with Claude Desktop-level capabilities**\n\nMCP-Ghost provides a programmatic interface for interacting with Model Context Protocol (MCP) servers through LLMs. Unlike CLI interfaces, MCP-Ghost accepts inputs directly from Python code and returns structured outputs with advanced tool orchestration features.\n\n## ✨ Features\n\n- 🔗 **Tool Chaining**: Automatically executes sequences of dependent tool calls\n- 🔄 **Backtracking**: Retries failed operations with alternative approaches  \n- 🧠 **Context Management**: Maintains conversation state across multiple tool interactions\n- 🛠️ **Error Recovery**: Intelligent handling of tool failures with retry strategies\n- 📊 **Result Synthesis**: Combines outputs from multiple tools into coherent responses\n\n## 🎯 Supported Providers\n\n- **OpenAI**: GPT-4o, GPT-4o-mini, GPT-4-turbo, GPT-3.5-turbo\n- **Anthropic (Claude)**: Claude-4-opus, Claude-4-sonnet, Claude-3.7-sonnet, Claude-3.5-sonnet, Claude-3-opus, Claude-3-sonnet, Claude-3-haiku  \n- **Google (Gemini)**: Gemini-2.5-pro, Gemini-2.5-flash, Gemini-2.0-flash, Gemini-1.5-pro, Gemini-1.5-flash\n\n> **💡 Recommended Models**: For best **cost-performance balance**, use **Claude-4-sonnet**, **Gemini-2.5-flash**, or **GPT-4o-mini**. For **maximum capability** in complex tool orchestration, use **Claude-4-opus** or **Gemini-2.5-pro**.\n\n## 📦 Installation\n\n```bash\npip install mcp-ghost\n```\n\n## 🚀 Quick Start\n\n```python\nimport asyncio\nfrom mcp_ghost import mcp_ghost, MCPGhostConfig\n\nasync def main():\n    # Option 1: Inline server config\n    config = MCPGhostConfig(\n        server_config={\n            \"mcpServers\": {\n                \"sqlite\": {\n                    \"command\": \"uvx\",\n                    \"args\": [\"mcp-server-sqlite\", \"--db-path\", \"test.db\"]\n                }\n            }\n        },\n        system_prompt=\"You are a helpful database assistant.\",\n        provider=\"openai\",\n        api_key=\"sk-...\",\n        user_prompt=\"List all tables and describe their schemas\"\n    )\n    \n    # Option 2: Load server config from file (Claude Desktop format)\n    config = MCPGhostConfig(\n        server_config=\"path/to/server_config.json\",  # or dict as above\n        system_prompt=\"You are a helpful database assistant.\",\n        provider=\"openai\", \n        api_key=\"sk-...\",\n        user_prompt=\"List all tables and describe their schemas\"\n    )\n    \n    result = await mcp_ghost(config)\n    print(f\"Success: {result.success}\")\n    print(f\"Summary: {result.summary}\")\n    print(f\"Tool calls made: {len(result.tool_chain)}\")\n\nif __name__ == \"__main__\":\n    asyncio.run(main())\n```\n\n## 🏗️ Architecture\n\nMCP-Ghost is designed for use in larger architectures where:\n\n1. **Human User** provides natural language input\n2. **Prompt Builder** processes user input and ensures security constraints\n3. **MCP-Ghost** executes the one-shot tool operation with intelligent orchestration\n4. **Results** are returned for further processing\n\n## 🔒 Security Model\n\n- **Prompt Builder Responsibility**: Input validation and security filtering\n- **MCP Server Trust**: Trusts provided MCP servers completely  \n- **Stdio Isolation**: Each MCP server runs in its own subprocess\n- **Timeout Protection**: Tool execution timeouts prevent hanging operations\n\n## 📖 Documentation\n\n- [Requirements Specification](docs/requirements.md)\n- [API Reference](docs/api.md)\n- [Examples](examples/)\n- [Testing Guide](docs/testing.md)\n\n## 🧪 Testing\n\nMCP-Ghost uses a focused core test suite for fast, reliable development:\n\n```bash\n# Run core functionality tests (recommended)\nmake test\n\n# Run all tests (requires external dependencies)\nmake test-all\n\n# Record new golden tests (requires API keys)\npytest -m record_golden\n```\n\nThe core test suite (145 tests) runs in ~1 second and covers all essential functionality without external dependencies.\n\n## 🤝 Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Add tests (including golden tests for new features)\n4. Submit a pull request\n\n## 📄 License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\nBuilt on top of:\n- [Official MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk) - Model Context Protocol implementation"}