Skip to content

Commit d91a49c

Browse files
committed
Add MCP server tester and update workspace configuration
- Introduced a new package `mcp_server_tester` in `Cargo.lock` with dependencies for testing MCP servers. - Updated `Cargo.toml` to include `tests/mcp_server_tester` as a member of the workspace for better organization. - Enhanced documentation in `TASKS.md` to outline the rewrite of MCP servers, detailing the hybrid approach and implementation phases. - Removed deprecated MCP server binaries (`command-mcp`, `filesystem-mcp`, `memory-store-mcp`) to streamline the project structure. - Improved logging and error handling in various modules to enhance maintainability and debugging capabilities.
1 parent 0e6d60f commit d91a49c

49 files changed

Lines changed: 2513 additions & 6028 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

.cursor/rules/01-project-overview.mdc

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -16,5 +16,5 @@ See the main [README.md](mdc:README.md) for a full overview.
1616
* **`gemini-mcp` ([mcp/README.md](mdc:mcp/README.md))**: Implements the Model Context Protocol (MCP) **host** side. Manages discovering, launching, and communicating with MCP **servers** (tools). Includes the `mcp-hostd` binary and built-in server implementations.
1717
* **`gemini-memory` ([memory/README.md](mdc:memory/README.md))**: Implements persistent semantic memory using LanceDB. Relies on an MCP host (`McpHostInterface`) for embedding generation.
1818
* **`gemini-cli` ([cli/README.md](mdc:cli/README.md))**: The main command-line interface. Integrates the other crates for user interaction, tool use, and memory.
19-
* **`HAPPE` ([HAPPE/README.md](mdc:HAPPE/README.md))**: Host Application Environment daemon. Manages interactions between user, LLM, `IDA`, and MCP servers. Intended as the primary execution environment.
20-
* **`IDA` ([IDA/README.md](mdc:IDA/README.md))**: Internal Dialogue App daemon. Manages persistent memory and background cognitive tasks, communicating with `HAPPE` via IPC.
19+
* **`HAPPE` (@happe/README.md)**: Host Application Environment daemon. Manages interactions between user, LLM, `IDA`, and MCP servers. Intended as the primary execution environment.
20+
* **`IDA` (@ida/README.md)**: Internal Dialogue App daemon. Manages persistent memory and background cognitive tasks, communicating with `HAPPE` via IPC.

.cursor/rules/05-daemons-ipc.mdc

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,8 +7,8 @@ alwaysApply: false
77

88
For more complex, persistent scenarios, the system uses background daemons communicating via Inter-Process Communication (IPC).
99

10-
* **`HAPPE` Daemon ([HAPPE/README.md](mdc:HAPPE/README.md))**: The Host Application Environment. Orchestrates user interactions, LLM calls, MCP tool execution, and communication with `IDA`.
11-
* **`IDA` Daemon ([IDA/README.md](mdc:IDA/README.md))**: Internal Dialogue App. Manages persistent memory interactions (retrieval/storage via Memory MCP Server) and other background cognitive tasks.
10+
* **`happe` Daemon (@happe/README.md)**: The Host Application Environment. Orchestrates user interactions, LLM calls, MCP tool execution, and communication with `IDA`.
11+
* **`ida` Daemon (@ida/README.md)**: Internal Dialogue App. Manages persistent memory interactions (retrieval/storage via Memory MCP Server) and other background cognitive tasks.
1212
* **`mcp-hostd` Daemon ([mcp/README.md](mdc:mcp/README.md))**: Standalone MCP host process. Manages connections to MCP tool servers.
1313
* **IPC Definitions (`gemini-ipc`)**: The `gemini-ipc` crate ([ipc/README.md](mdc:ipc/README.md)) centralizes message structures for communication between these components.
1414
* `internal_messages.rs` ([ipc/src/internal_messages.rs](mdc:ipc/src/internal_messages.rs)): Defines messages between `HAPPE` and `IDA`.

Cargo.lock

Lines changed: 14 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

Cargo.toml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@ members = [
1111
"install", # Installer crate for Gemini CLI Suite
1212
"daemon-manager", # CLI for managing gemini-suite daemons and MCP servers
1313
"tools", # Tools for configuration, maintenance, etc.
14+
"tests/mcp_server_tester", # Test binary for MCP Python servers
1415
]
1516

1617
[workspace.lints]

QUERY_FLOW.md

Lines changed: 129 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,129 @@
1+
# End-to-End Query Flow
2+
3+
This document outlines the full lifecycle of a user query as it travels from the End User through the HAPPE daemon, internal communication with the IDA daemon, interactions with MCP servers, calls to the main LLM API, and back to the End User. It also covers the asynchronous memory storage process.
4+
5+
---
6+
7+
## Overview of Components
8+
9+
- **End User**: The person or client application issuing a natural language query.
10+
- **HAPPE (Host Application Environment)**: Orchestrates user interactions, LLM calls, and MCP tool execution; communicates with IDA via IPC.
11+
- **IDA (Internal Dialogue App)**: Manages persistent memory: retrieves context and stores completed turns; communicates over IPC with HAPPE.
12+
- **Memory MCP Server**: Provides memory retrieval and storage via MCP protocol.
13+
- **Other MCP Servers**: Hosts additional MCP tools invoked during LLM generation.
14+
- **Main LLM API**: The external LLM endpoint that generates natural language responses.
15+
16+
---
17+
18+
## Sequence Diagram
19+
20+
```mermaid
21+
sequenceDiagram
22+
autonumber
23+
participant User as End User
24+
participant HAPPE as HAPPE Daemon
25+
participant IDA as IDA Daemon
26+
participant MemMCP as Memory MCP Server
27+
participant MCP as Other MCP Server(s)
28+
participant LLM as Main LLM API
29+
30+
User->>HAPPE: Query Request (query, session_id)
31+
activate HAPPE
32+
33+
HAPPE->>IDA: GetMemoriesRequest (query, context)
34+
activate IDA
35+
36+
IDA->>MemMCP: retrieve_memories(query, ...)
37+
activate MemMCP
38+
note right of IDA: Semantic search + optional Broker LLM filtering
39+
MemMCP-->>IDA: Vec<Memory>
40+
deactivate MemMCP
41+
42+
IDA-->>HAPPE: GetMemoriesResponse { memories }
43+
deactivate IDA
44+
45+
HAPPE->>HAPPE: Construct Prompt
46+
activate LLM
47+
HAPPE->>LLM: generate_response(contents, system_prompt, tools)
48+
49+
alt Function Call requested by LLM
50+
LLM-->>HAPPE: function_calls: Vec<FunctionCall>
51+
activate MCP
52+
HAPPE->>MCP: execute_tool(server, tool, args)
53+
MCP-->>HAPPE: result: JSON
54+
deactivate MCP
55+
HAPPE-->>LLM: Part::function_response(name, result)
56+
end
57+
58+
LLM-->>HAPPE: Final Response (text, calls)
59+
deactivate LLM
60+
61+
HAPPE-->>User: Query Response (response, session_id)
62+
63+
note over HAPPE, IDA: Asynchronous Storage
64+
HAPPE-)+IDA: StoreTurnRequest { turn_data }
65+
activate IDA
66+
IDA-)MemMCP: storage::handle_storage(...)
67+
activate MemMCP
68+
MemMCP--)IDA: Result<()>
69+
deactivate MemMCP
70+
deactivate IDA
71+
deactivate HAPPE
72+
```
73+
74+
---
75+
76+
## Detailed Step-by-Step Flow
77+
78+
1. **End User -> HAPPE**
79+
- The end user or client application sends a raw text query to the HAPPE daemon over the chosen transport (e.g., HTTP, WebSocket, CLI).
80+
- This is represented internally as `HappeQueryRequest { query, session_id }`.
81+
82+
2. **HAPPE -> IDA (IPC)**
83+
- HAPPE immediately forwards the raw query to the IDA daemon via IPC using `InternalMessage::GetMemoriesRequest { query, conversation_context }`.
84+
- The IPC transport is configured in HAPPE's settings (Unix socket path).
85+
86+
3. **IDA -> Memory MCP Server (MCP)**
87+
- Upon receiving the query, IDA invokes the memory MCP server with `retrieve_memories(query, max_results, broker_llm)`.
88+
- The memory store performs semantic search and optionally filters results using a broker LLM.
89+
90+
4. **Memory MCP -> IDA**
91+
- The memory service returns a list of relevant `Memory` objects (e.g., past messages, facts).
92+
- IDA converts these to `MemoryItem` objects and prepares an `InternalMessage::GetMemoriesResponse` to send back.
93+
94+
5. **IDA -> HAPPE (IPC Response)**
95+
- IDA sends the retrieved memories back to HAPPE over the same IPC channel.
96+
97+
6. **HAPPE Prompt Construction**
98+
- HAPPE builds prompt parts that include memories and the user query.
99+
- It prepares the prompt with a system message that includes MCP capabilities.
100+
- Example: `"Relevant previous interactions: <memory_1>\n<memory_2>\n<original query>"`.
101+
102+
7. **HAPPE -> Main LLM API Call**
103+
- HAPPE calls `generate_response` with the constructed contents, system prompt, and available tools.
104+
- Common parameters include conversation history, current query content, and tool declarations.
105+
106+
8. **Tool Invocation (Optional)**
107+
- If the LLM returns function calls, HAPPE processes each call:
108+
- Extracts server name and tool name from the function call name
109+
- Calls `mcp_client.execute_tool(server_name, tool_name, arguments)`
110+
- Adds the tool result as a `Part::function_response` to the conversation
111+
- Makes another LLM request with the updated history including the tool results
112+
113+
9. **LLM -> HAPPE Response**
114+
- The LLM returns the final `(response_text, function_calls)` tuple once all tool calls (if any) are resolved.
115+
116+
10. **HAPPE -> End User**
117+
- HAPPE returns `HappeQueryResponse { response, session_id }` to the user over the original transport.
118+
119+
11. **Asynchronous Memory Storage**
120+
- HAPPE sends an async `InternalMessage::StoreTurnRequest { turn_data }` to IDA containing:
121+
- `user_query`: The original query string
122+
- `retrieved_memories`: The memories used in the prompt
123+
- `llm_response`: The final text response
124+
- `turn_parts`: The full conversation turn parts
125+
- IDA spawns a background task via `storage::handle_storage` to process and store the turn.
126+
127+
---
128+
129+
*End of document.*

TASKS.md

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -324,3 +324,62 @@ This phase adds a stateful session management system to HAPPE, allowing it to ma
324324
- [ ] **Integration Tests:** Test IPC handler with session history.
325325
- [ ] **End-to-End Tests (`@cli` -> `happe-daemon`):** Verify context is maintained across multiple turns within a single CLI run.
326326
- [ ] **Refinement:** Assess performance, history pruning, error handling, security of session IDs.
327+
328+
## Phase 11: Rewrite MCP Servers (Hybrid Approach - Python Facades, Rust Core Memory)
329+
330+
This phase replaces `filesystem-mcp` and `command-mcp` with Python implementations. `memory-store-mcp` becomes a Python facade process, while its core logic (including vector store via `gemini-memory`) is embedded and executed directly within `mcp-hostd.rs`.
331+
332+
### Sub-Phase 1: Investigation & Design Refinement
333+
334+
- [x] **Analyze `mcp-hostd.rs` & `gemini_mcp` Crate:** (Config loading/launching confirmed).
335+
- [x] **Analyze `install` Crate:** (Binary/config handling understood).
336+
- [x] **Analyze `gemini-memory` Dependency:** (Will be embedded in `mcp-hostd`).
337+
- [x] **Refine Design:** Confirm hybrid strategy:
338+
- [x] `mcp-hostd` embeds `gemini_memory::MemoryStore`.
339+
- [x] `mcp-hostd` intercepts & handles `memory-store-mcp/*` tool calls internally.
340+
- [x] Minimal `memory-store-mcp.py` facade launched via stdio for handshake.
341+
- [x] Standard `filesystem-mcp.py` and `command-mcp.py` servers.
342+
343+
### Sub-Phase 2: Implementation
344+
345+
- [ ] **Modify `mcp-hostd.rs` (Initialization):**
346+
- [ ] Ensure `gemini-memory` dependency available to `mcp-hostd`.
347+
- [ ] Initialize `MemoryStore` instance during startup.
348+
- [ ] Load necessary `MemoryStore` config (DB path, etc.) from main `config.toml`.
349+
- [ ] Store `Arc<MemoryStore>` where `process_request` can access it.
350+
- [ ] **Modify `mcp-hostd.rs` (`process_request`):**
351+
- [ ] Add logic to intercept `ExecuteTool` for `server == "memory-store-mcp"`.
352+
- [ ] Implement internal calls to embedded `MemoryStore` for intercepted requests.
353+
- [ ] Bypass standard `host.execute_tool` for these intercepted requests.
354+
- [ ] **Modify `mcp-hostd.rs` (Capabilities):**
355+
- [ ] Manually add tool definitions for internal memory operations under the `memory-store-mcp` server name during capability aggregation.
356+
- [ ] **Implement `python_mcp/servers/base_server.py` (as before).**
357+
- [ ] **Implement `python_mcp/servers/filesystem_mcp.py` (as before).**
358+
- [ ] **Implement `python_mcp/servers/command_mcp.py` (as before).**
359+
- [ ] **Simplify `python_mcp/servers/memory_store_mcp.py`:**
360+
- [ ] Remove `MemoryStore` class and tool handlers.
361+
- [ ] `main` should only create `McpBaseServer`, register no tools, and call `run()`.
362+
- [ ] **Project Setup (`python_mcp`, `requirements.txt` - as before).**
363+
364+
### Sub-Phase 3: Integration & Installation
365+
366+
- [ ] **Modify `install/src/main.rs`:**
367+
- [ ] Remove Rust MCP binary installation steps.
368+
- [ ] Add step to copy `python_mcp` directory to installation target.
369+
- [ ] Modify `install_unified_config`:
370+
- [ ] Generate `mcp_servers.json` entries pointing all 3 servers (`memory-store-mcp`, `filesystem-mcp`, `command-mcp`) to their Python scripts.
371+
- [ ] Ensure main `config.toml` generation includes necessary `[memory]` / `[ida]` sections for embedded `MemoryStore` config.
372+
373+
### Sub-Phase 4: Testing & Deployment
374+
375+
- [ ] Build & Install modified `install` crate.
376+
- [ ] Verify Python scripts and config files placement.
377+
- [ ] Install Python dependencies (`pip install -r requirements.txt`).
378+
- [ ] Start `mcp-hostd`. Check logs for embedded `MemoryStore` init & Python process handshakes.
379+
- [ ] IPC Client Testing:
380+
- [ ] Test `GetCapabilities` (should show memory tools listed under `memory-store-mcp`).
381+
- [ ] Test `filesystem-mcp` tools (check Python logs).
382+
- [ ] Test `command-mcp` tools (check Python logs).
383+
- [ ] Test `memory-store-mcp` tools (check `mcp-hostd` logs & DB state).
384+
- [ ] Shutdown Testing.
385+
- [ ] Deployment.

0 commit comments

Comments
 (0)