README.md•7.79 kB
# EX MCP Server
[](https://github.com/Zazzles2908/EX_AI-mcp-server/actions/workflows/test.yml)
[](LICENSE)


EX MCP Server is a Model Context Protocol (MCP) server that connects modern LLM providers and tools to MCP‑compatible clients (e.g., Claude Desktop/CLI). It provides a unified set of analysis, debugging, refactoring, documentation, testing, and project automation tools accessible over the MCP stdio protocol.
## Key Capabilities
- Unified MCP server exposing rich development tools:
- analyze, codereview, debug, refactor, tracer, testgen, precommit, listmodels, version
- Provider integrations:
- KIMI (Moonshot), GLM (Zhipu), OpenRouter, and custom OpenAI‑compatible endpoints
## Quick Links
- O&M Manual: [docs/o_and_m_manual/](docs/o_and_m_manual/)
- Chat Sheet: [docs/o_and_m_manual/CHAT_SHEET.md](docs/o_and_m_manual/CHAT_SHEET.md)
- Augment Code Guidelines (EXAI‑MCP default): [docs/policies/AUGMENT_CODE_GUIDELINES.md](docs/policies/AUGMENT_CODE_GUIDELINES.md)
- Sweep Reports: [docs/sweep_reports/](docs/sweep_reports/)
- MCP‑first architecture:
- Subprocess stdio transport with direct config examples for Claude Desktop/CLI
- Docker and local dev support:
- Docker image build/publish, local virtualenv (.venv), and cross‑platform scripts
## Installation
### Prerequisites
- Python 3.9+
- Git
- For local dev: virtualenv support
- Optional: Docker and Docker Compose
### Clone
```
git clone https://github.com/BeehiveInnovations/ex-mcp-server.git
cd ex-mcp-server
```
### Setup (local)
```
python -m venv .venv
# Windows
.venv\\Scripts\\activate
# macOS/Linux
source .venv/bin/activate
pip install -r requirements.txt
pip install -r requirements-dev.txt
cp .env.example .env
# Set at least one provider key (KIMI_API_KEY, GLM_API_KEY, OPENROUTER_API_KEY, or CUSTOM_API_URL/CUSTOM_API_KEY)
```
### Run (local)
```
python -m server # or: python server.py
```
### Configure a client (Claude Desktop/CLI)
Minimal example (stdio):
```
{
"mcpServers": {
"ex": {
"type": "stdio",
"trust": true,
"command": "python",
"args": ["-u", "scripts/mcp_server_wrapper.py"],
"cwd": "/absolute/path/to/ex-mcp-server",
"env": {
"MCP_SERVER_NAME": "ex",
"MCP_SERVER_ID": "ex-server",
"PYTHONPATH": "/absolute/path/to/ex-mcp-server",
"ENV_FILE": "/absolute/path/to/ex-mcp-server/.env"
}
}
}
}
```
See the examples/ directory for more configs (macOS, WSL, desktop CLI variants).
## Docker
Build and run locally:
```
docker build -t ex-mcp-server:latest .
docker run --rm -it ex-mcp-server:latest
```
A reverse proxy example is provided (nginx.conf) and a remote compose file (docker-compose.remote.yml) that exposes the server as ex-mcp.
## Usage Overview
- Use the version tool to verify install:
```
# In Claude Desktop config, call the version tool
```
- Common tools:
- analyze: smart file analysis
- codereview: professional code review
- debug: debugging assistant
- refactor: code refactoring
- tracer: static analysis / call chain aid
- testgen: test generation
- precommit: quick pre-commit validation
- listmodels: show available models/providers
### Provider‑native Web Browsing Schemas
- Kimi (Moonshot): inject an OpenAI function tool named "web_search" with a string parameter "query".
- GLM (Zhipu): enable tools = [{"type":"web_search","web_search":{}}] only when allowed by env.
- Set these via env for production readiness:
- KIMI_ENABLE_INTERNET_TOOL=true and KIMI_INTERNET_TOOL_SPEC to a valid JSON tool schema
- GLM_ENABLE_WEB_BROWSING=true when appropriate (and other GLM browsing flags as documented)
## Hidden Model Router (Auto Model Selection)
The server can auto-select a concrete model at the MCP boundary so users don’t need to specify one.
- Enable: HIDDEN_MODEL_ROUTER_ENABLED=true
- Sentinels: ROUTER_SENTINEL_MODELS=glm-4.5-flash,auto
- Default: DEFAULT_MODEL=glm-4.5-flash (a sentinel)
Behavior:
- If a tool requires a model and incoming model is a sentinel (or "auto"), the server resolves a concrete model.
- Structured logs emitted by the server (logger name: "server"):
- EVENT boundary_model_resolution_attempt input_model=... tool=... sentinel_match=... hidden_router=...
- EVENT boundary_model_resolved input_model=... resolved_model=... tool=...
Notes:
- The Consensus tool intentionally does not resolve models at the MCP boundary (requires_model = False). You will see the "attempt" log at the boundary, and per-step model selection happens inside the tool.
Tip: Use listmodels to see configured providers/models.
## Agentic Audit with Real Models (EX‑AI)
Use a consensus-based, multi-model audit to find issues and get direct fixes.
1) Set provider keys in .env:
- KIMI_API_KEY=...
- GLM_API_KEY=...
2) Run the audit script:
```
python scripts/exai_agentic_audit.py --models glm-4.5-air kimi-k2-0905-preview
```
Or rely on env defaults (GLM_AUDIT_MODEL, KIMI_AUDIT_MODEL) and just:
```
python scripts/exai_agentic_audit.py
```
The script returns JSON:
```
{
"issues": [ { "title": str, "evidence": str, "direct_fix": str }... ],
"summary": str
}
```
3) Interpreting results:
- Each issue has “direct_fix” with exactly what to change and where.
- Re-run after fixes to validate improvements.
## Tests: End-to-end (no real keys required)
We include an “ultimate” test file designed for EX‑AI‑style validation:
- tests/test_e2e_exai_ultimate.py
- Each assert prints a Direct Fix if it fails.
- Run: `python -m pytest -q tests/test_e2e_exai_ultimate.py`
### CI/Test Hygiene (EX fork)
This fork disables some upstream providers by design. If you run the full test suite, import errors may occur for those optional providers.
See docs/ci-test-notes.md for ways to skip/guard those tests in CI.
## Configuration
- Environment file: .env (see .env.example for available variables)
- Key variables:
- DEFAULT_MODEL, LOCALE, MAX_MCP_OUTPUT_TOKENS
- Provider keys: KIMI_API_KEY, GLM_API_KEY, OPENROUTER_API_KEY
- Custom API: CUSTOM_API_URL, CUSTOM_API_KEY
- Logging: logs/ directory (Docker and local scripts manage ownership/paths)
## Attribution
This project is based on the original work at:
- https://github.com/BeehiveInnovations/zen-mcp-server
We have forked/copied and adapted it to create EX MCP Server. Attribution to the original authors is preserved.
## Our EX‑specific Changes (Zen → EX)
- Rebranding:
- Service name: zen-mcp → ex-mcp
- Non-root user: zenuser → exuser (Dockerfile, file ownership)
- Virtual environment: .zen_venv → .venv
- Branding strings: “Zen MCP Server” → “EX MCP Server”
- Examples/configs:
- Server IDs: "zen" → "ex"
- Commands: zen-mcp-server → ex-mcp-server
- Paths updated to ex-mcp-server
- CI/workflows & templates:
- GitHub discussions/links point to ex-mcp-server
- GHCR image names: ghcr.io/<org>/ex-mcp-server:...
- Architecture intent:
- MCP-first stdio transport, reverse proxy alignment, and consistent service naming
## Contributing
Please see CONTRIBUTING.md for development workflow, coding standards, and testing.
## License
See the LICENSE file in this repository.
## Additional Resources
- MCP Spec: https://modelcontextprotocol.io/
- Claude Desktop docs for MCP: https://docs.anthropic.com/claude/docs/model-context-protocol
- Original source (upstream): https://github.com/BeehiveInnovations/zen-mcp-server
- Current project: https://github.com/BeehiveInnovations/ex-mcp-server