Commit 7898dbb

@@ -0,0 +1,127 @@
+## 📄 MCP Design Document: Go Implementation
+
+**Project Name:** `mcp`
+**Target Repository:** `https://github.com/xlgmokha/mcp`
+**Primary Language:** Go
+**Structure:** Multi-command architecture using `cmd/` folder to organize multiple protocol servers.
+
+---
+
+### 🧱 Overall Project Structure
+
+```
+mcp/
+├── go.mod
+├── go.sum
+├── README.md
+├── internal/
+│   └── shared/          # Reusable logic/utilities across commands
+├── pkg/
+│   └── mcp/             # Shared MCP protocol tooling (e.g., request/response structs)
+└── cmd/
+    ├── git/
+    │   └── main.go      # Git server
+    ├── <future-server>/
+    │   └── main.go      # Placeholder for future mcp servers
+```
+
+---
+
+### 🚀 Phase 1: Implementing `cmd/git`
+
+#### Objective
+
+Replicate the functionality of the [Python git server](https://github.com/modelcontextprotocol/servers/tree/main/src/git) from the MCP project in Go.
+
+#### Features
+
+The Go server must:
+
+1. Accept stdin JSON requests conforming to the MCP protocol (e.g. `{"action": "list", "repo": "https://github.com/..."} `).
+2. Support these commands:
+
+   * `clone`: Clone a remote Git repository.
+   * `list`: List files in the repo (default to `HEAD`).
+   * `read`: Read file contents at specific paths.
+   * `head`: Show latest commit hash.
+3. Return responses as JSON to stdout.
+4. Print logs and errors to stderr.
+5. Be able to work as a CLI tool or JSON-RPC-compatible stdin/stdout process.
+
+#### External Dependencies
+
+* `go-git` ([https://github.com/go-git/go-git](https://github.com/go-git/go-git)) for Git operations.
+* Optional: `spf13/cobra` if command-line execution is needed in the future.
+
+#### Internal Structure for Git Server
+
+```
+cmd/git/
+├── main.go
+├── handler.go         # MCP request router
+├── gitutils.go        # Git operations: clone, read, list, head
+```
+
+#### JSON Message Format
+
+Request (stdin):
+
+```json
+{
+  "action": "list",
+  "repo": "https://github.com/modelcontextprotocol/servers",
+  "ref": "HEAD"
+}
+```
+
+Response (stdout):
+
+```json
+{
+  "status": "ok",
+  "files": ["README.md", "src/git/main.py", ...]
+}
+```
+
+On error:
+
+```json
+{
+  "status": "error",
+  "error": "failed to clone repository"
+}
+```
+
+---
+
+### 🧠 Design Principles
+
+* **Modular design:** Each server is a self-contained CLI app under `cmd/`.
+* **Streaming stdin/stdout:** Allow compatibility with tools like OpenAI functions or Claude tool use.
+* **Lightweight and efficient:** Avoid unnecessary dependencies.
+* **Testable:** Extract logic from `main.go` to make unit testing easier.
+
+---
+
+### 🛣️ Future Work (beyond git)
+
+* `cmd/fs/main.go`: Local filesystem server.
+* `cmd/bash/main.go`: Command-line interpreter over MCP.
+* `cmd/sql/main.go`: SQL query server.
+* `cmd/http/main.go`: Interact with HTTP APIs.
+* `cmd/gpt/main.go`: Call local or remote LLMs.
+* `cmd/py/main.go`: Execute Python snippets.
+
+Each command can follow the same pattern: read JSON input from stdin, process, write JSON to stdout.
+
+---
+
+### ✅ Acceptance Criteria
+
+* Running `go run cmd/git/main.go` with valid input via stdin performs the Git actions as expected.
+* Fails gracefully with meaningful stderr logs and proper JSON error responses.
+* Repository includes:
+
+  * `README.md` with usage instructions.
+  * Example inputs/outputs for testing.
+  * Clear instructions to add more commands under `cmd/`.