lhumina_code/home
22
0
Fork 0
Code Issues 3 Pull requests Projects Releases Packages Wiki Activity Actions

Clean MCP architecture: shrimp direct spawning, aibroker as pure LLM proxy #36

New issue
Closed
opened 2026-03-18 16:56:43 +00:00 by mik-tf · 1 comment
mik-tf commented 2026-03-18 16:56:43 +00:00
Owner
Copy link

Context

With #34 adding MCP endpoints to all services and #27 standardizing server lifecycle via HeroRpcServer, the MCP client-side architecture needs cleanup.

Problem

Today there are two parallel MCP paths from the AI Assistant to services:

  1. Broker-mediated: shrimp → aibroker REST /tools → aibroker spawns bridges → services
  2. Direct stdio: shrimp → spawns bridges itself → JSON-RPC over stdio → services

This creates:

  • Two config formats (mcp_servers.json array vs mcp.json object)
  • Two process lifecycle managers (aibroker + shrimp both spawn bridges)
  • Unclear context injection (who sets HERO_CONTEXT?)

Proposed Architecture

Server-side (covered by #27 + #34)

  • Every service exposes POST /mcp (auto-generated from OpenRPC by HeroRpcServer)
  • Context passed via _context parameter in JSON-RPC
  • OpenRPC is the single source of truth — MCP tools are derived, not hand-written

Client-side (this issue)

  • hero_shrimp owns MCP tool management — spawns bridge processes directly (standard Claude Desktop pattern)
  • hero_aibroker becomes pure LLM proxy — drop MCP aggregation code, focus on API key management, model routing, provider fallback
  • Single config: mcp.json in Claude Desktop object format
  • Context injection: shrimp injects HERO_CONTEXT into system prompt; LLM passes context param to tools

What changes

Component Current Target
hero_shrimp mcp_manager.ts Spawns bridges from mcp.json Keep as-is (already correct pattern)
hero_shrimp mcp.ts Calls aibroker REST /tools Remove — no longer needed
hero_aibroker MCP aggregation Spawns bridges, exposes /tools REST Remove — aibroker is LLM-only
mcp_servers.json Array format for aibroker Remove — replaced by mcp.json
mcp.json Claude Desktop object format Keep — single source of truth
build-local.sh transform Converts array→object format Remove — no longer needed

Benefits

  • Less code (remove ~200 lines from aibroker, ~100 from shrimp)
  • One config format (Claude Desktop standard)
  • Clean separation: aibroker = LLM routing, shrimp = agent + tools
  • Standard pattern (same as Claude Desktop, Cursor, etc.)
  • Simpler context flow

Dependencies

  • #34 — MCP endpoints on all services (done)
  • #27 — HeroRpcServer auto-generates /mcp from OpenRPC (proposed)

Non-blocking

Both paths work today. This is a cleanup for architectural clarity, not a blocker.

## Context With #34 adding MCP endpoints to all services and #27 standardizing server lifecycle via `HeroRpcServer`, the MCP client-side architecture needs cleanup. ## Problem Today there are **two parallel MCP paths** from the AI Assistant to services: 1. **Broker-mediated**: shrimp → aibroker REST `/tools` → aibroker spawns bridges → services 2. **Direct stdio**: shrimp → spawns bridges itself → JSON-RPC over stdio → services This creates: - Two config formats (`mcp_servers.json` array vs `mcp.json` object) - Two process lifecycle managers (aibroker + shrimp both spawn bridges) - Unclear context injection (who sets `HERO_CONTEXT`?) ## Proposed Architecture ### Server-side (covered by #27 + #34) - Every service exposes `POST /mcp` (auto-generated from OpenRPC by `HeroRpcServer`) - Context passed via `_context` parameter in JSON-RPC - OpenRPC is the single source of truth — MCP tools are derived, not hand-written ### Client-side (this issue) - **hero_shrimp owns MCP tool management** — spawns bridge processes directly (standard Claude Desktop pattern) - **hero_aibroker becomes pure LLM proxy** — drop MCP aggregation code, focus on API key management, model routing, provider fallback - **Single config**: `mcp.json` in Claude Desktop object format - **Context injection**: shrimp injects `HERO_CONTEXT` into system prompt; LLM passes `context` param to tools ### What changes | Component | Current | Target | |-----------|---------|--------| | hero_shrimp `mcp_manager.ts` | Spawns bridges from `mcp.json` | Keep as-is (already correct pattern) | | hero_shrimp `mcp.ts` | Calls aibroker REST `/tools` | **Remove** — no longer needed | | hero_aibroker MCP aggregation | Spawns bridges, exposes `/tools` REST | **Remove** — aibroker is LLM-only | | `mcp_servers.json` | Array format for aibroker | **Remove** — replaced by `mcp.json` | | `mcp.json` | Claude Desktop object format | **Keep** — single source of truth | | build-local.sh transform | Converts array→object format | **Remove** — no longer needed | ### Benefits - Less code (remove ~200 lines from aibroker, ~100 from shrimp) - One config format (Claude Desktop standard) - Clean separation: aibroker = LLM routing, shrimp = agent + tools - Standard pattern (same as Claude Desktop, Cursor, etc.) - Simpler context flow ## Dependencies - #34 — MCP endpoints on all services (done) - #27 — `HeroRpcServer` auto-generates `/mcp` from OpenRPC (proposed) ## Non-blocking Both paths work today. This is a cleanup for architectural clarity, not a blocker.
mik-tf commented 2026-03-18 23:16:25 +00:00
Author
Owner
Copy link

Implemented — MCP architecture cleaned up

hero_shrimp (branch development_mik_6_1):

  • Deleted src/core/mcp.ts (aibroker REST /tools discovery)
  • Removed discoverMCPTools() from loader.ts
  • Kept mcp_manager.ts (direct bridge spawning from mcp.json)
  • Shrimp now loads MCP tools only from local bridge processes

hero_aibroker (branch development_mik_6_1):

  • Deleted entire src/mcp/ module (client, config, manager, server, types) — ~1000 lines
  • Removed MCP initialization, state field, and 4 RPC handlers from main.rs
  • Deleted mcp_servers.json
  • Aibroker is now LLM-proxy only

Result: Single MCP path — shrimp spawns bridges directly via mcp.json. No aibroker intermediary.

Commits:

  • hero_shrimp@7196db1 on development_mik_6_1 (PR #11)
  • hero_aibroker@2b37446 on development_mik_6_1 (PR #27)
## Implemented — MCP architecture cleaned up **hero_shrimp** (branch `development_mik_6_1`): - Deleted `src/core/mcp.ts` (aibroker REST /tools discovery) - Removed `discoverMCPTools()` from `loader.ts` - Kept `mcp_manager.ts` (direct bridge spawning from `mcp.json`) - Shrimp now loads MCP tools only from local bridge processes **hero_aibroker** (branch `development_mik_6_1`): - Deleted entire `src/mcp/` module (client, config, manager, server, types) — ~1000 lines - Removed MCP initialization, state field, and 4 RPC handlers from `main.rs` - Deleted `mcp_servers.json` - Aibroker is now LLM-proxy only **Result**: Single MCP path — shrimp spawns bridges directly via `mcp.json`. No aibroker intermediary. Commits: - hero_shrimp@7196db1 on `development_mik_6_1` (PR #11) - hero_aibroker@2b37446 on `development_mik_6_1` (PR #27)
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
development
main
No results found.
Labels
Clear labels
No items
No labels
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
lhumina_code/home#36
No description provided.