@ace-sdk/mcp

MCP Server for ACE pattern learning - works with any MCP-compatible client.

Installation

npm install @ace-sdk/mcp

Features

• 15 MCP Tools: Full ACE functionality as MCP tools
• Client Agnostic: Works with Claude Code, Cursor, Cline, VSCode Copilot, or any MCP client
• ACE 1.5 Reward Model: Patterns ranked by cumulative_v15_reward + hot/warm/cold tier counters. helpful/harmful are deprecated derived read-only values.
• Task Intent Routing: ace_search accepts task_intent (refactor | routine | explore | spec_strict) and exploration_enabled/exploration_rate to steer the server-side LinUCB bandit.
• F-080 Feedback Loop: ace_search forwards its session_id (auto-generated or caller-supplied) in the POST /patterns/search body, stamping retrieval_log_v15.session_id on the server. ace_learn then rebuilds applied_log_ids from the session's stored match_factors and sends retrieval_id + applied_log_ids on every trace — closing the reward learning loop without manual wiring.
• SQLite Graph Cache: Persistent 7-day TTL store at ~/.ace-cache/<org>__<project>.db (one file per org+project). Caches patterns, playbook, embeddings, and co-application graph edges. Same DB read by ace-desktop Brain-Graphs.
• expanded Graph Neighbors: Every ace_search response includes an expanded array of id-only stubs (pattern_id + cumulative_v15_reward) for up to 2-hop co-application graph neighbors of the primary hits. Stubs are deduped against primary results and token-efficient. Hydrate selectively via ace_batch_get. Requires the optional better-sqlite3 dep; degrades gracefully when absent.
• Project-Scoped Graph Endpoint: GET /patterns/graph requires the X-ACE-Project header (set automatically by the MCP server). Edges are refreshed at most once per hour per search call.

MCP Client Setup

Add to your MCP configuration (e.g., .mcp.json):

{
  "mcpServers": {
    "ace-pattern-learning": {
      "command": "npx",
      "args": ["@ace-sdk/mcp"],
      "env": {
        "ACE_SERVER_URL": "https://ace-api.code-engine.app",
        "ACE_PROJECT_ID": "your-project"
      }
    }
  }
}

With user authentication (ace-cli login), ACE_API_TOKEN is not required. The MCP server reads credentials from ~/.config/ace/config.json.

ACE 1.5 Example

// 1. Search with task intent — server routes via LinUCB bandit
ace_search({
  query: "refactor payment module",
  task_intent: "refactor"        // steers bandit; omit to use server default
  // session_id: "...",          // optional — auto-generated if omitted
  // exploration_enabled: true,  // optional override
  // exploration_rate: 0.25,     // optional override
})
// MCP sends POST /patterns/search { ..., session_id: "<uuid>" }
// Server stamps retrieval_log_v15.session_id — links this search to the later trace (F-080)
// Response carries:
//   session_id  — auto-generated UUID (forward to ace_learn)
//   retrieval_id  — top-level UUID for F-080
//   results[n].cumulative_v15_reward  — primary ranking signal
//   results[n].effectiveness.recommendation  — "highly_reliable" | "reliable" | ...
//   results[n].match_factors.retrieval_log_id  — integer key for F-080
//   results[n].match_factors.ucb_score / bandit_rank  — when LinUCB is warm
//   expanded  — id-only stubs for 2-hop graph neighbors (pattern_id + cumulative_v15_reward)
//              hydrate with ace_batch_get({ pattern_ids: expanded.map(n => n.pattern_id) })

// 2. Do the work ...

// 3. Learn — F-080 loop closes automatically
ace_learn({
  task: "Refactored payment module",
  trajectory: ["Extracted PaymentService", "Added error boundaries"],
  success: true,
  output: "Lessons learned...",
  session_id: "550e8400-e29b-41d4-a716-446655440000"  // from step 1 response
  // ACE 1.5: retrieval_id + applied_log_ids auto-carried on the trace
})

Available Tools

| Tool | Description | |------|-------------| | ace_get_playbook | Fetch learned patterns (all sections) | | ace_search | Semantic search with reward model, task_intent, exploration knobs, and expanded 2-hop graph neighbors (ACE 1.5) | | ace_learn | Submit execution traces — F-080 feedback loop via session_id (ACE 1.5) | | ace_top_patterns | Top patterns by cumulative_v15_reward (ACE 1.5) | | ace_bootstrap | Initialize playbook from codebase | | ace_status | Get playbook statistics | | ace_delta | Manual pattern management | | ace_cache_clear | Clear local caches (RAM + SQLite graph cache) | | traces_list | List recent execution traces with filters | | traces_get | Fetch full trace detail including ACE 1.5 F-080 fields |

Migrating from ACE 1.0

ACE 1.5 is a clean-break MAJOR — no backward-compat shim in the write path.

| Change | What to do | |--------|-----------| | helpful/harmful removed from write path | Remove any code that PATCH-votes helpful/harmful. Read-only derived getters still present for old clients. | | cumulative_v15_reward is the new ranking signal | Sort/filter on cumulative_v15_reward; ≤ 0.0 = at-risk pattern. | | match_factors on search results | No action — MCP stores them in the session automatically. | | F-080: retrieval_id + applied_log_ids on traces | Pass session_id from ace_search to ace_learn; loop closes automatically. | | New SQLite graph cache | Old 5-min KV files are ignored; new schema created on first use. | | expanded in ace_search response | No action needed — stubs appear automatically. Hydrate with ace_batch_get as needed. | | Package version | @ace-sdk/mcp → v3.0.0 |

Documentation

Full documentation: sdks/typescript/mcp/docs

License

MIT © CE.NET Team