A previous release had provenance metadata, but this release does not. View details.
This release is a pre-release and may not be stable for production use.
ensemble-mcp
A harness infrastructure layer delivered as a Python MCP server — providing vector memory, drift detection, model routing, skills discovery, session management, codebase indexing, and context compression for AI agent pipelines.
All intelligence is local — zero LLM/API calls. Uses ONNX Runtime embeddings (~5ms), numpy cosine similarity, and SQLite storage.
What is an Agent Harness?
Agent = Model + Harness. A harness is every piece of code, configuration, and execution logic that wraps a model to turn it into a useful agent. Without a harness, a model can only take in text and output text — it can't maintain state, execute code, access tools, or learn from past work.
A complete agent harness typically includes:
- System prompts & configuration — instructions that shape agent behavior
- Tools, Skills & MCPs — capabilities the agent can invoke
- Execution environment — filesystem, bash, sandbox, browser
- Orchestration logic — subagent spawning, handoffs, model routing
- Memory & context management — compaction, skills, session persistence
- Hooks & middleware — deterministic checks like linting, formatting, drift detection
For a deeper dive, see The Anatomy of an Agent Harness by LangChain.
Where ensemble-mcp Fits
Agent harnesses like Claude Code, Codex, and Cursor provide the execution layer — filesystem, bash, sandbox. ensemble-mcp provides the intelligence infrastructure layer that plugs into any harness via MCP:
┌─────────────────────────────────────────────────────────┐
│ AGENT HARNESS │
│ │
│ ┌───────────────────────────────────────────────────┐ │
│ │ Execution Layer │ │
│ │ (provided by Claude Code / Codex / Cursor) │ │
│ │ │ │
│ │ ┌──────────┐ ┌──────────┐ ┌──────────────────┐ │ │
│ │ │Filesystem│ │ Bash / │ │ Sandbox / │ │ │
│ │ │ & Git │ │ Code │ │ Browser │ │ │
│ │ └──────────┘ └──────────┘ └──────────────────┘ │ │
│ └───────────────────────────────────────────────────┘ │
│ │
│ ┌───────────────────────────────────────────────────┐ │
│ │ Intelligence Infrastructure Layer │ │
│ │ (provided by ensemble-mcp via MCP) │ │
│ │ │ │
│ │ ┌────────┐ ┌────────┐ ┌───────┐ ┌───────────┐ │ │
│ │ │ Memory │ │ Skills │ │ Drift │ │ Context │ │ │
│ │ │& Search│ │ │ │Detect │ │Compression│ │ │
│ │ └────────┘ └────────┘ └───────┘ └───────────┘ │ │
│ │ ┌────────┐ ┌────────┐ ┌───────┐ ┌───────────┐ │ │
│ │ │ Model │ │Session │ │Code │ │ Project │ │ │
│ │ │Routing │ │Persist.│ │Index │ │ Snapshot │ │ │
│ │ └────────┘ └────────┘ └───────┘ └───────────┘ │ │
│ └───────────────────────────────────────────────────┘ │
│ │
│ ┌───────────────────────────────────────────────────┐ │
│ │ Orchestration Layer │ │
│ │ (agent pipeline, subagent spawning, handoffs) │ │
│ └───────────────────────────────────────────────────┘ │
│ │
│ ┌───────────┐ │
│ │ MODEL │ │
│ └───────────┘ │
└─────────────────────────────────────────────────────────┘
Features
ensemble-mcp provides these harness primitives:
| Harness Primitive | Feature | What It Does |
|---|---|---|
| Memory & Search | Pattern Memory | Semantic vector search over stored pipeline patterns (MiniLM-L6-v2, 384-dim) |
| Drift Detection | Drift Check | Cosine similarity between task description and code changes |
| Model Routing | Model Recommend | Recommend model tier (best/mid/cheapest) per agent and task complexity |
| Skills (Progressive Disclosure) | Skills Discovery | Scan .ai/skills/, .claude/skills/, .cursor/rules/ etc. with semantic search |
| Skills (Progressive Disclosure) | Skill Intelligence | Auto-detect recurring patterns and suggest converting them to reusable skills |
| Long Horizon Execution | Session Management | Pipeline checkpoint save/load with optimistic versioning |
| Codebase Awareness | Codebase Indexing | File-level index with exports, imports, roles — incremental via mtime |
| Context Rot Prevention | Context Compression | Compress verbose text into token-efficient form, rule-based |
| Context Rot Prevention | Prompt Caching | Order and prepare prompt sections for optimal LLM cache hit rates |
| Codebase Awareness | Codebase Snapshots | Generate compact project baseline summaries from the codebase index |
| Harness Setup | Auto-Installer | Detect AI tools and register the MCP server in their configs |
| Observability | Web Dashboard | Local browser UI at localhost:8787 for visualizing patterns, skills, projects, drift, and sessions |
Quick Start
Install from source
git clone https://github.com/LynkByte/ensemble.git
cd ensemble
pip install -e ".[dev]"
Install via uvx (after PyPI publish)
uvx ensemble-mcp
Run the server
# Start the MCP server (stdio protocol)
ensemble-mcp
# Or explicitly
ensemble-mcp serve
Other CLI commands
# Auto-detect AI tools and register the MCP server
ensemble-mcp install
# Remove MCP server registration from AI tool configs
ensemble-mcp uninstall
# Copy agent files to a project (no MCP registration needed)
ensemble-mcp add-agents --tools opencode
# Copy skill files to a project (no MCP registration needed)
ensemble-mcp add-skills --tools opencode
Web Dashboard
A local-only browser dashboard for visualizing patterns, skills, projects, drift history, and sessions.
# Start the dashboard (opens browser to http://localhost:8787)
ensemble-mcp web
# Custom port
ensemble-mcp web --port 9000
# Start without auto-opening the browser
ensemble-mcp web --no-open
# Specify a reports directory (auto-detected from ./reports or git root otherwise)
ensemble-mcp web --reports-dir /path/to/reports
The dashboard reads directly from the same SQLite database the MCP server writes to (WAL mode, no contention). It binds to 127.0.0.1 only — never exposed to the network, no authentication needed.
Dashboard Pages
| Page | What It Shows |
|---|---|
| Overview | Summary cards (patterns, skills, projects, drift checks), drift score trend chart, recent activity |
| Patterns | All stored patterns with match counts, project filtering, search |
| Skills | Pending skill suggestions with confidence scores, stale skill detection |
| Projects | Indexed projects with language breakdown pie charts, file role bar charts, export counts |
| Drift | Drift check history with scores, verdicts, flagged files, project filtering |
| Sessions | Session list with lifecycle status, click-through to step-by-step detail |
API Endpoints
All endpoints return the standard ok/data/error/meta envelope:
| Endpoint | Description |
|---|---|
GET /api/summary |
Aggregate counts and recent activity |
GET /api/patterns |
Paginated pattern list (filter by project) |
GET /api/patterns/:id |
Single pattern detail with embedding metadata |
GET /api/skills |
Skill suggestions (filter by project, status) |
GET /api/skills/stale |
Skills not matched within threshold days |
GET /api/projects |
Indexed projects with file/export counts |
GET /api/projects/:path |
Project detail with language and role breakdown |
GET /api/drift |
Drift history (filter by project, from, to) |
GET /api/sessions |
Paginated session list (filter by project, status) |
GET /api/sessions/:id |
Session detail with steps |
GET /api/health |
Server health, version, DB size |
MCP Client Configuration
OpenCode
Add to ~/.config/opencode/config.json or project config.json:
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"ensemble": {
"type": "local",
"command": ["uvx", "ensemble-mcp"]
}
}
}
Or for a local development install:
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"ensemble": {
"type": "local",
"command": ["/path/to/venv/bin/ensemble-mcp"]
}
}
}
Claude Code
Add to ~/.claude/claude_desktop_config.json:
{
"mcpServers": {
"ensemble": {
"command": "uvx",
"args": ["ensemble-mcp"]
}
}
}
GitHub Copilot (VS Code)
Add to .vscode/mcp.json:
{
"servers": {
"ensemble": {
"command": "uvx",
"args": ["ensemble-mcp"]
}
}
}
Cursor
Add to ~/.cursor/mcp.json:
{
"mcpServers": {
"ensemble": {
"command": "uvx",
"args": ["ensemble-mcp"]
}
}
}
Windsurf
Add to ~/.windsurf/mcp.json:
{
"mcpServers": {
"ensemble": {
"command": "uvx",
"args": ["ensemble-mcp"]
}
}
}
Auto-Install
Instead of manual configuration, run the installer to auto-detect installed AI tools and register the server:
# Detect tools and register (interactive)
ensemble-mcp install
# Register specific tools only
ensemble-mcp install --tools opencode,cursor
# Preview without making changes
ensemble-mcp install --dry-run
# Non-interactive
ensemble-mcp install --yes
The installer automatically detects how ensemble-mcp is available on your system and registers the appropriate command:
| Priority | Detection | Registered Command |
|---|---|---|
| 1st | ensemble-mcp on PATH (pip/pipx install) |
ensemble-mcp |
| 2nd | uvx on PATH |
uvx ensemble-mcp |
| 3rd | Neither found | /path/to/python -m ensemble_mcp (current interpreter) |
19 MCP Tools
Patterns (semantic memory)
| Tool | Description |
|---|---|
patterns_search |
Semantic search over stored patterns |
patterns_store |
Store a new pattern with embedding |
patterns_prune |
Remove old/unused patterns |
Drift Detection
| Tool | Description |
|---|---|
drift_check |
Cosine similarity between task and changes (0-1 score) |
Model Routing
| Tool | Description |
|---|---|
model_recommend |
Recommend model tier for agent + task complexity |
Skills
| Tool | Description |
|---|---|
skills_discover |
Scan skill directories with optional semantic search |
skills_suggest |
Detect recurring patterns, propose as reusable skills |
skills_generate |
Accept, dismiss, or defer a skill suggestion |
Session
| Tool | Description |
|---|---|
session_save |
Save pipeline checkpoint with optimistic versioning |
session_load |
Load latest or specific checkpoint |
session_search |
Search sessions by semantic similarity |
Codebase Indexer
| Tool | Description |
|---|---|
project_index |
Build/refresh file-level codebase index |
project_query |
Query index by language, path, or text |
project_dependencies |
Get import/dependency graph for a file |
project_snapshot |
Generate compact project baseline summary (cached) |
Context Compression
| Tool | Description |
|---|---|
context_compress |
Compress verbose text into terse, token-efficient form while preserving technical content |
context_prepare |
Order prompt sections for optimal LLM cache hit rates (static → project → task) |
Utility
| Tool | Description |
|---|---|
health |
Server health check |
reset |
Reset all data (destructive, requires confirmation) |
Response Envelope
Every tool returns a standardized envelope:
{
"ok": true,
"data": { "matches": [...] },
"error": null,
"meta": {
"duration_ms": 12,
"source": "sqlite",
"confidence": "exact"
}
}
Confidence indicators: exact (direct data), partial (mixed sources), estimated (heuristic).
Architecture
ensemble-mcp is structured as a harness infrastructure layer with clear separation between tool implementations and shared engine components:
ensemble-mcp/
src/ensemble_mcp/
server.py # MCP server + tool registration
config/ # Settings, defaults
contracts/ # Response envelope, error taxonomy
memory/ # ONNX embeddings, SQLite vector store, cosine similarity
security/ # Secret redaction, trust boundaries
state/ # Session/step lifecycle, idempotency, locks
tools/ # 19 MCP tool implementations + call-recording utility
installer/ # AI tool detection + MCP registration
dashboard/ # Web dashboard (aiohttp server, JSON API, SPA frontend)
compress/ # Rule-based text compression engine (context rot prevention)
cli/ # Startup banner
data/ # Bundled agent and skill files (AGENTS.md, skills)
Technology Stack
| Component | Choice |
|---|---|
| Language | Python 3.11+ |
| Distribution | uvx (zero-hassle cross-platform) |
| MCP Framework | mcp (official Python SDK) |
| Embeddings | ONNX Runtime + MiniLM-L6-v2 (~22MB, 384-dim) |
| Vector Storage | SQLite + numpy cosine similarity |
| Tokenizer | HuggingFace tokenizers (for MiniLM input) |
| Package Size | ~90MB (including ONNX + model) |
Local Storage
| Path | Contents |
|---|---|
~/.cache/ensemble-mcp/data.db |
SQLite database (WAL mode) |
~/.cache/ensemble-mcp/models/ |
ONNX MiniLM-L6-v2 model (~22MB) |
~/.config/ensemble-mcp/config.toml |
Global user configuration |
Configuration
Layered config with deterministic merge order:
- Package defaults (built-in)
- Global config (
~/.config/ensemble-mcp/config.toml) - Project config (
.ensemble-mcp.toml) - Environment variables (
ENSEMBLE_MCP_*)
# ~/.config/ensemble-mcp/config.toml
drift_threshold_aligned = 0.25
default_top_k = 5
cluster_similarity_threshold = 0.8
Development
# Install with dev dependencies
pip install -e ".[dev]"
# Run tests
python -m pytest tests/ -v
# Lint
ruff check src/ tests/
# Format
ruff format src/ tests/
# Type check
mypy src/
# Build package
python -m build
Docker
docker build -t ensemble-mcp .
docker run --rm -v ~/.cache/ensemble-mcp:/home/app/.cache/ensemble-mcp ensemble-mcp
Eval Framework
Benchmark suite for measuring tool effectiveness:
# Run eval benchmarks
python evals/runner.py
# Or via pytest
python -m pytest evals/ -v
Supported AI Tools
| AI Tool | Config Format | Auto-Install |
|---|---|---|
| OpenCode | JSON | Yes |
| Claude Code | JSON | Yes |
| GitHub Copilot (VS Code) | JSON | Yes |
| Cursor | JSON | Yes |
| Windsurf | JSON | Yes |
| Devin CLI | JSON | Yes |
License
Metadata
Release files for ensemble-mcp 0.1.0b7
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Loss of provenance
These files do not have provenance metadata, despite files in a prior release including this data.
We recommend further investigation before installing these files. View details.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| ensemble_mcp-0.1.0b7.tar.gz | 3.6 MB | Without provenance | Details for ensemble_mcp-0.1.0b7.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| ensemble_mcp-0.1.0b7-py3-none-any.whl | Python 3 | none | any | Details for ensemble_mcp-0.1.0b7-py3-none-any.whl |
Total release size: 3.8 MB
Release files / ensemble_mcp-0.1.0b7.tar.gz
Loss of provenance
This file belongs to a release without provenance metadata, despite a prior release including this data.
We recommend further investigation before installing this file. View details.
| Download URL | ensemble_mcp-0.1.0b7.tar.gz |
|---|---|
| Size | 3.6 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
95bb3917dbe47dd53c288d2d7f4f4a966ba57b3006cf675f36b2e8c92f33ba1b
|
|
BLAKE2b-256 checksum How to use checksums |
e4004674be25b5e30bf1f0207185aaebc2f47f5400b8141da312016d672cb16d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.3
|
Release files / ensemble_mcp-0.1.0b7-py3-none-any.whl
Loss of provenance
This file belongs to a release without provenance metadata, despite a prior release including this data.
We recommend further investigation before installing this file. View details.
| Download URL | ensemble_mcp-0.1.0b7-py3-none-any.whl |
|---|---|
| Size | 156.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
14a02a030e9e6371ce94232e45c98fe9f3d2e92401cc13672fdf0bc2b44394bc
|
|
BLAKE2b-256 checksum How to use checksums |
0be4fbb479a593f66574364f34ebacd4521c5b1a30d9fd6b83303052aa1d8542
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.3
|
Security for ensemble-mcp 0.1.0b7
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Loss of provenance
A previous release of these files had provenance metadata, but this release does not.
While this could reflect a routine change by the project maintainers, it may also indicate that the release files have been compromised.
Release comparison
- Removed 0.1.0b6 2 files With provenance
- Added 0.1.0b7 2 files Without provenance
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.