Skip to content
This repository was archived by the owner on Apr 23, 2025. It is now read-only.

Commit 9cc1c8f

Browse files
ipv1337ipv1337
committed
docs: Add MCP and UV migration plans, update diagram validation
1 parent de30b21 commit 9cc1c8f

3 files changed

Lines changed: 268 additions & 0 deletions

File tree

‎docs/DIAGRAM_VALIDATION.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,9 @@ After making changes to Mermaid diagrams in the documentation, follow these step
1313
- Simplify complex diagrams that may exceed GitHub's rendering capabilities.
1414
- Remove special styling, if present.
1515
- Ensure proper indentation and avoid special characters.
16+
- **Check for extraneous characters:** Ensure lines don't have unintended trailing characters, especially after semicolons.
17+
- **Quote complex labels:** Enclose node labels in double quotes (`""`) if they contain HTML (like `<br>`), markdown, punctuation (like `()`, `,`, `/`), or other non-alphanumeric characters (excluding underscores). When in doubt, quote the label. (e.g., `NodeId["Label line 1<br>Label line 2"]`, `AnotherId["My Label (New)"]`).
18+
- **Use specific types:** Prefer explicitly listed types (like `flowchart TD`) over more general ones (`graph TD`) if encountering issues.
1619

1720
## Mermaid Version Check
1821

‎docs/mcp_integration_plan.md‎

Lines changed: 195 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,195 @@
1+
# MCP Integration Plan for cli-code
2+
3+
This document outlines the plan to refactor `cli-code` from direct LLM API integration to using the Model Context Provider (MCP) protocol. This involves transforming `cli-code` into an MCP client and creating a dedicated MCP server to handle LLM communication and tool execution, while retaining the focus as a specialized AI coding assistant.
4+
5+
## 1. Architecture Overview (C4 Model)
6+
7+
We will adopt a client-server architecture. `cli-code` acts as the client, providing the user interface, while a new `MCP Server` handles backend logic.
8+
9+
### Level 1: System Context
10+
11+
```mermaid
12+
flowchart TD
13+
User[User] -- Interacts via Terminal --> CLI["cli-code (Client)"];
14+
CLI -- Sends/Receives MCP Messages --> MCPServer["MCP Server (New)"];
15+
MCPServer -- Interacts with --> Workspace["User's Workspace/File System"];
16+
MCPServer -- Sends Prompts/Receives Completions --> LLM_API["LLM APIs (Gemini, Ollama, etc.)"]
17+
```
18+
19+
* **User:** The developer using the terminal.
20+
* **cli-code (Client):** The existing CLI application, refactored to be an MCP client. Responsible for UI, sending user input, and displaying server responses (including text and tool activity).
21+
* **MCP Server (New):** A new server application responsible for MCP protocol handling, LLM interaction, and executing coding-specific tools against the user's workspace.
22+
* **User's Workspace/File System:** Where the code resides and where tools like file operations and terminal commands are executed by the server.
23+
* **LLM APIs:** External services like Google Gemini or local Ollama instances that provide the language model capabilities.
24+
25+
### Level 2: Containers
26+
27+
```mermaid
28+
flowchart TD
29+
subgraph "User System"
30+
User[User]
31+
end
32+
33+
subgraph "AI Coding Assistant System"
34+
User -- Uses --> CLIClient["cli-code (CLI Application)<br>Python<br>Handles UI, MCP Client Logic"];
35+
CLIClient -- Communicates via MCP over TCP/IP --> MCPServer["MCP Server (Server Application)<br>Python<br>Handles MCP Protocol, LLM Interaction, Tool Execution"];
36+
end
37+
38+
subgraph "External Systems"
39+
LLM_APIs["LLM Provider APIs<br>(Gemini, Ollama)"];
40+
Workspace[File System / Terminal];
41+
end
42+
43+
MCPServer -- Makes API Calls --> LLM_APIs;
44+
MCPServer -- Reads/Writes Files, Runs Commands --> Workspace;
45+
```
46+
47+
* **cli-code (CLI Application):** The Python application running in the user's terminal. Contains UI logic and an MCP client component (`chuk-mcp`).
48+
* **MCP Server (Server Application):** A separate Python process. Contains MCP protocol handling logic, LLM client implementations (Gemini, Ollama), and the tool execution engine.
49+
50+
### Level 3: Components (Conceptual)
51+
52+
```mermaid
53+
flowchart TD
54+
subgraph CLIClient [cli-code Client]
55+
direction LR
56+
UI["UI Manager<br>(Rich, Prompt Toolkit)"]
57+
Chat[Chat Handler]
58+
MCPClient["MCP Client Wrapper<br>(using chuk-mcp)"]
59+
60+
UI -- User Input --> Chat;
61+
Chat -- Sends Messages --> MCPClient;
62+
MCPClient -- Receives Messages --> Chat;
63+
Chat -- Updates --> UI;
64+
end
65+
66+
subgraph MCPServer [MCP Server]
67+
direction LR
68+
Listener["API Listener<br>(e.g., asyncio sockets)"]
69+
MCPHandler["MCP Protocol Handler<br>(using chuk-mcp concepts)"]
70+
LLMClients["LLM Clients<br>(Gemini, Ollama)"]
71+
ToolExecutor["Tool Executor<br>(File Ops, Terminal, Lint, Test)"]
72+
73+
Listener -- Receives MCP --> MCPHandler;
74+
MCPHandler -- Interacts with --> LLMClients;
75+
MCPHandler -- Triggers --> ToolExecutor;
76+
ToolExecutor -- Executes Tools --> Workspace[(File System / Terminal)];
77+
ToolExecutor -- Results --> MCPHandler;
78+
LLMClients -- Results --> MCPHandler;
79+
MCPHandler -- Sends MCP --> Listener;
80+
end
81+
82+
CLIClient -- MCP --> MCPServer;
83+
```
84+
85+
## 2. Interaction Flow (Sequence Diagram)
86+
87+
```mermaid
88+
sequenceDiagram
89+
participant User
90+
participant CLI [cli-code Client]
91+
participant MCPServer [MCP Server]
92+
participant LLM [LLM API]
93+
participant Tools [Tool Executor]
94+
95+
User->>+CLI: Enter message (e.g., "Read file main.py")
96+
CLI->>+MCPServer: Send MCP User Message
97+
MCPServer->>+LLM: Send prompt to LLM
98+
LLM-->>-MCPServer: Receive LLM response (requests tool call: read_file)
99+
MCPServer->>+CLI: Send MCP Assistant Message (e.g., "Okay, I will read the file.")
100+
CLI-->>-User: Display "Okay, I will read the file."
101+
MCPServer->>+CLI: Send MCP Tool Call Request (read_file: main.py)
102+
CLI-->>User: Display "[Tool Call: read_file('main.py')]"
103+
MCPServer->>+Tools: Execute read_file('main.py')
104+
Tools-->>-MCPServer: Return file content
105+
MCPServer->>+CLI: Send MCP Tool Result (content of main.py)
106+
CLI-->>User: Display "[Tool Result: <file content>]" (optional, or just indicate success)
107+
MCPServer->>+LLM: Send tool result to LLM
108+
LLM-->>-MCPServer: Receive final LLM response (e.g., "Here is the content...")
109+
MCPServer->>+CLI: Send MCP Assistant Message ("Here is the content...")
110+
CLI-->>-User: Display final response
111+
```
112+
113+
## 3. Roadmap & Milestones
114+
115+
This roadmap breaks the implementation into manageable milestones. Each milestone will be developed on a separate feature branch, ensuring adherence to development practices before merging into `main`.
116+
117+
* **M1: Setup & Basic Client Connection** (`feature/mcp-client-setup`)
118+
* Add `chuk-mcp` dependency to `cli-code`.
119+
* Create a *stub* MCP server (minimal listener, echoes messages).
120+
* Refactor `cli-code`'s main chat loop to connect to the stub server using `chuk-mcp`.
121+
* Implement basic sending of user messages and receiving/displaying text responses via MCP.
122+
* Ensure tests pass (>80% coverage) and linters are clean.
123+
124+
* **M2: Basic Server Implementation** (`feature/mcp-server-basic`)
125+
* Develop a functional MCP server application skeleton.
126+
* Implement MCP protocol handling on the server.
127+
* Integrate one LLM provider (e.g., Gemini) into the server.
128+
* Server proxies simple text messages between `cli-code` and the LLM.
129+
* Configure server connection details (e.g., host/port) possibly via env vars initially.
130+
* Ensure server tests pass (>80% coverage) and linters are clean.
131+
132+
* **M3: Tool Interaction Display (Client)** (`feature/mcp-client-tool-display`)
133+
* Modify `cli-code` UI to correctly parse and display MCP messages related to tool calls (Tool Call Request, Tool Result) originating from the server.
134+
* No tool *execution* logic in the client.
135+
* Update client tests.
136+
137+
* **M4: Server-Side Core Tool Execution** (`feature/mcp-server-core-tools`)
138+
* Implement execution logic for core file system tools (`read_file`, `edit_file`, `list_dir`, `file_search`, `grep_search`) within the `MCP Server`.
139+
* Server receives tool call requests from LLM, executes them, and sends results back.
140+
* *Remove* the corresponding tool execution logic from `cli-code`.
141+
* Add server tests for tool execution. Update client tests.
142+
143+
* **M5: Server-Side Advanced Tool Execution** (`feature/mcp-server-advanced-tools`)
144+
* Implement execution logic for advanced tools (`run_terminal_cmd`, linting, testing) on the `MCP Server`.
145+
* **Crucially:** Implement security measures (sandboxing, path validation) for `run_terminal_cmd`.
146+
* *Remove* the corresponding tool execution logic from `cli-code`.
147+
* Add server tests for these tools. Update client tests.
148+
149+
* **M6: Configuration & Multi-Provider Support** (`feature/mcp-config-multiprovider`)
150+
* Refine configuration handling in `cli-code` to specify the MCP server address (`config.yaml`, env vars).
151+
* Implement logic (likely server-side) to manage and select between multiple LLM providers (Gemini, Ollama) based on configuration or client request.
152+
* Update configuration documentation (`docs/install.md`).
153+
* Update tests.
154+
155+
* **M7: Deployment & Packaging** (`feature/mcp-deployment`)
156+
* Decide on the server deployment strategy (e.g., run as a background process started by `cli-code`, separate installation, containerization).
157+
* Update `pyproject.toml` and packaging scripts (`setup.py` or equivalent) if the server needs to be bundled or installed alongside the client.
158+
* Update installation and usage documentation (`README.md`, `docs/install.md`).
159+
160+
* **M8: Refinement & Final Documentation** (`feature/mcp-refinement`)
161+
* Conduct end-to-end testing.
162+
* Perform code cleanup and final refactoring based on testing.
163+
* Ensure all documentation is up-to-date with the new architecture.
164+
* Final check of test coverage and linter compliance.
165+
166+
## 4. Development Practices
167+
168+
For *each* milestone:
169+
170+
1. **Feature Branch:** All work will be done on a dedicated feature branch (e.g., `feature/mcp-client-setup`).
171+
2. **Small Commits:** Use small, logical commits with clear messages.
172+
3. **Code Coverage:** Maintain >80% unit test coverage for all *new* and *modified* code in both `cli-code` and the new `MCP Server` application. Coverage checks must pass in CI.
173+
4. **Linting:** All code must pass configured linter checks (e.g., Ruff, MyPy) in CI.
174+
5. **Pull Request:** Submit a Pull Request to `main` upon completion of the milestone.
175+
6. **CI Pipeline:** The PR must pass all checks in the CI pipeline (tests, linting, coverage) before merging.
176+
177+
## 5. Additional Considerations
178+
179+
* **Security:** This is paramount, especially for the `run_terminal_cmd` tool. The MCP server *must* be designed with security in mind.
180+
* **Sandboxing:** Explore using containers or restricted shells for executing terminal commands.
181+
* **Path Validation:** Ensure file operations are strictly limited to the intended project workspace. Validate paths thoroughly.
182+
* **Input Sanitization:** Sanitize arguments passed to tools.
183+
* **Permissions:** Run the server process with the least privilege necessary.
184+
* **Server Deployment:** How will users run the MCP Server?
185+
* **Option A (Bundled):** `cli-code` starts/manages the server process in the background. Simplest for users, but couples the client and server lifecycles.
186+
* **Option B (Separate):** Users install and run the server separately. More flexible, allows independent updates, but adds a step for the user.
187+
* **Option C (Hosted):** A remote server (less likely for this use case due to local file access needs).
188+
* *Recommendation:* Start with Option A or B (local process).
189+
* **Error Handling:** Implement robust error handling for network issues between client/server, LLM API errors, and tool execution failures. Propagate errors meaningfully back to the user via MCP messages.
190+
* **Configuration:** How will the server know which workspace context to operate in? This likely needs to be passed during connection setup from `cli-code` or configured separately for the server.
191+
* **State Management:** Consider if any state needs to be shared or synchronized between the client and server beyond standard MCP messages.
192+
* **Dependency (`chuk-mcp`):** Ensure compatibility and understand the maintenance status of the chosen MCP library.
193+
* **Future Protocol Implementation:** While using `chuk-mcp` initially accelerates development, consider potentially developing an in-house MCP protocol handler in the future. This could offer more control and faster adaptation if the MCP standard evolves significantly or if `chuk-mcp` development lags behind desired features.
194+
* **Performance:** Monitor for any noticeable latency introduced by the client-server hop, although it's expected to be minor for this use case.
195+
```

‎docs/uv_migration_plan.md‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
# UV Package Manager Migration Plan
2+
3+
This document outlines the plan to migrate the `cli-code` project from using `pip` and `venv` to using `uv` for environment and package management.
4+
5+
## 1. Rationale
6+
7+
Switching to `uv` aims to:
8+
9+
* **Improve Development Speed:** Leverage `uv`'s significantly faster dependency resolution and installation capabilities compared to `pip`.
10+
* **Streamline Workflows:** Utilize `uv`'s unified command-line interface for environment creation (`uv venv`), installation (`uv pip install`, `uv sync`), and potentially locking (`uv pip compile`).
11+
* **Enhance CI/CD Efficiency:** Reduce the time taken for dependency installation steps in the GitHub Actions workflow.
12+
* **Align with Modern Tooling:** Adopt a actively developed tool from the creators of Ruff.
13+
14+
## 2. Migration Milestones
15+
16+
This migration will be performed on a dedicated feature branch (e.g., `feature/uv-migration`) following the established development practices.
17+
18+
* **M1: Local Validation & Setup** (`feature/uv-migration`)
19+
* Developers install `uv` locally.
20+
* Verify core local workflows:
21+
* Create virtual environment: `uv venv`
22+
* Install dependencies from `pyproject.toml` for development: `uv pip install -e .[dev]` (or similar depending on group definitions)
23+
* Run linters (Ruff, MyPy).
24+
* Run tests (`pytest`).
25+
* Confirm basic project functionality remains unchanged.
26+
* Document any immediate issues or necessary adjustments.
27+
* Commit initial findings and successful local workflow commands.
28+
29+
* **M2: Update Documentation** (`feature/uv-migration`)
30+
* Modify `README.md`: Update installation and setup sections to use `uv` commands.
31+
* Modify `docs/install.md`: Update detailed installation and setup instructions.
32+
* Modify `docs/contributing.md`: Update development environment setup guide.
33+
* Ensure consistency across all documentation referencing environment setup or package installation.
34+
* Commit documentation changes.
35+
36+
* **M3: Update CI Workflow** (`feature/uv-migration`)
37+
* Modify `.github/workflows/python-ci.yml`:
38+
* Add a step to install `uv` itself early in the job.
39+
* Replace `pip install` commands with equivalent `uv pip install` or `uv sync` commands for installing project dependencies and test requirements.
40+
* Trigger CI runs and verify all jobs pass successfully using `uv`.
41+
* Commit CI workflow changes.
42+
43+
* **M4: Final Review & Merge** (`feature/uv-migration`)
44+
* Review all project files (scripts, docs, configs) for any lingering `pip`-specific commands or references that should be updated or removed.
45+
* Consider removing `requirements.txt` files if they were only used for `pip` installation and locking isn't managed by `uv pip compile` yet (if applicable).
46+
* Perform a final check of local workflows and CI pipeline status.
47+
* Submit Pull Request for review and merge into `main`.
48+
49+
## 3. Development Practices
50+
51+
For *this migration*:
52+
53+
1. **Feature Branch:** All work will be done on the `feature/uv-migration` branch.
54+
2. **Small Commits:** Use small, logical commits for each milestone step.
55+
3. **Testing/Linting:** Ensure all existing tests and linter checks pass after switching local commands to `uv`.
56+
4. **CI Pipeline:** The primary goal is to ensure the CI pipeline passes using `uv` for dependency management in M3.
57+
5. **Pull Request:** Submit a Pull Request to `main` upon completion of M4.
58+
59+
## 4. Files Potentially Modified
60+
61+
* `README.md`
62+
* `docs/install.md`
63+
* `docs/contributing.md`
64+
* `.github/workflows/python-ci.yml`
65+
* (Potentially remove/ignore `requirements*.txt` files if switching locking mechanism, TBD)
66+
67+
## 5. Considerations
68+
69+
* **Lock Files:** This plan focuses on replacing `pip install` and `venv`. We can decide later whether to also replace `pip-tools` with `uv pip compile` for managing lock files (`requirements.txt`/`.lock`). For now, `uv pip install -r requirements.txt` can still be used if needed.
70+
* **Developer Adoption:** Ensure all active developers are aware of the switch and update their local environments/workflows.

0 commit comments

Comments
 (0)