minder-cli 0.2.0__py3-none-any.whl

minder/transport/sse.py

@@ -0,0 +1,252 @@
+import json
+import logging
+from contextlib import AsyncExitStack
+from contextlib import asynccontextmanager
+from typing import AsyncIterator
+from typing import Any
+
+import uvicorn
+from starlette.applications import Starlette
+from starlette.middleware.cors import CORSMiddleware
+from starlette.requests import Request
+from starlette.responses import JSONResponse
+from starlette.routing import BaseRoute
+from starlette.types import ASGIApp
+from starlette.types import Receive
+from starlette.types import Scope
+from starlette.types import Send
+from minder.auth.context import set_current_principal
+from minder.auth.service import AuthService
+from minder.config import MinderConfig
+from minder.presentation.http.admin.routes import dashboard_dev_origin
+from minder.observability.logging import (
+    AccessLogMiddleware,
+    CorrelationIdMiddleware,
+    GlobalExceptionMiddleware,
+)
+from minder.store.interfaces import ICacheProvider, IOperationalStore
+from minder.transport.base import BaseTransport
+
+logger = logging.getLogger(__name__)
+
+
+class MCPCompatApp:
+    def __init__(self, *, sse_app: ASGIApp, streamable_http_app: ASGIApp) -> None:
+        self._sse_app = sse_app
+        self._streamable_http_app = streamable_http_app
+
+    @staticmethod
+    def _rewrite_path(scope: Scope, path: str) -> Scope:
+        updated_scope = dict(scope)
+        updated_scope["path"] = path
+        updated_scope["raw_path"] = path.encode("utf-8")
+        return updated_scope
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        if scope["type"] != "http":
+            await self._streamable_http_app(scope, receive, send)
+            return
+
+        path = scope.get("path", "")
+        method = scope.get("method", "GET").upper()
+
+        if path == "/sse" and method in {"GET", "HEAD"}:
+            await self._sse_app(scope, receive, send)
+            return
+
+        if path.startswith("/messages"):
+            await self._sse_app(scope, receive, send)
+            return
+
+        if path == "/sse" and method in {"POST", "DELETE", "OPTIONS"}:
+            await self._streamable_http_app(
+                self._rewrite_path(scope, "/mcp"), receive, send
+            )
+            return
+
+        await self._streamable_http_app(scope, receive, send)
+
+
+class SSEAuthMiddleware:
+    def __init__(self, app: Any, auth_service: AuthService) -> None:
+        self.app = app
+        self.auth_service = auth_service
+
+    async def __call__(self, scope: Any, receive: Any, send: Any) -> Any:
+        if scope["type"] != "http":
+            return await self.app(scope, receive, send)
+
+        headers = dict(scope.get("headers", []))
+        auth_header = headers.get(b"authorization")
+        client_key_header = headers.get(b"x-minder-client-key")
+
+        # If we have an auth header and it's a POST,
+        # we'll intercept the body to inject the authorization token as a hidden param.
+        if (auth_header or client_key_header) and scope["method"] == "POST":
+            auth_token = auth_header.decode("utf-8") if auth_header else None
+            client_key = (
+                client_key_header.decode("utf-8") if client_key_header else None
+            )
+
+            async def wrapped_receive() -> Any:
+                message = await receive()
+                if message["type"] == "http.request":
+                    body = message.get("body", b"")
+                    if body:
+                        try:
+                            # Attempt to inject _authorization into the JSON-RPC arguments
+                            data = json.loads(body)
+                            if (
+                                isinstance(data, dict)
+                                and data.get("method") == "tools/call"
+                            ):
+                                params = data.setdefault("params", {})
+                                args = params.setdefault("arguments", {})
+                                # Only inject if not already present
+                                if auth_token and "minder_authorization" not in args:
+                                    args["minder_authorization"] = auth_token
+                                if client_key and "minder_client_key" not in args:
+                                    args["minder_client_key"] = client_key
+                                new_body = json.dumps(data).encode("utf-8")
+                                message["body"] = new_body
+                        except Exception:
+                            pass  # Fallback to original body if parsing fails
+                return message
+
+            # Also set the context var just in case it can propagate
+            try:
+                if client_key:
+                    principal = await self.auth_service.get_principal_from_client_key(
+                        client_key
+                    )
+                else:
+                    assert auth_token is not None
+                    token = auth_token.strip()
+                    if token.lower().startswith("bearer "):
+                        token = token[7:].strip()
+                    principal = await self.auth_service.get_principal_from_token(token)
+                set_current_principal(principal)
+            except Exception:
+                pass
+
+            return await self.app(scope, wrapped_receive, send)
+
+        return await self.app(scope, receive, send)
+
+
+class SSETransport(BaseTransport):
+    transport_name = "sse"
+
+    def __init__(
+        self,
+        *,
+        config: MinderConfig,
+        store: IOperationalStore | None = None,
+        auth_service: AuthService | None = None,
+        extra_routes: list[BaseRoute] | None = None,
+        cache_provider: ICacheProvider,
+    ) -> None:
+        super().__init__(
+            config=config,
+            auth_service=auth_service,
+            cache_provider=cache_provider,
+            store=store,
+        )
+        self._extra_routes = list(extra_routes or [])
+        self._legacy_sse_app: Starlette | None = None
+        self._streamable_http_app: Starlette | None = None
+
+    def extend_routes(self, routes: list[BaseRoute]) -> None:
+        self._extra_routes.extend(routes)
+
+    @staticmethod
+    async def _oauth_protected_resource_metadata(request: Request) -> JSONResponse:
+        base_url = str(request.base_url).rstrip("/")
+        return JSONResponse(
+            {
+                "resource": f"{base_url}/mcp",
+                "authorization_servers": [],
+            }
+        )
+
+    @asynccontextmanager
+    async def _app_lifespan(self, app: Starlette) -> AsyncIterator[None]:
+        del app
+        async with AsyncExitStack() as stack:
+            if self._legacy_sse_app is not None:
+                await stack.enter_async_context(
+                    self._legacy_sse_app.router.lifespan_context(self._legacy_sse_app)
+                )
+            if self._streamable_http_app is not None:
+                await stack.enter_async_context(
+                    self._streamable_http_app.router.lifespan_context(
+                        self._streamable_http_app
+                    )
+                )
+            yield
+
+    def build_starlette_app(self) -> Starlette:
+        legacy_sse_app: Starlette = self._server.sse_app()
+        streamable_http_app: Starlette = self._server.streamable_http_app()
+        self._legacy_sse_app = legacy_sse_app
+        self._streamable_http_app = streamable_http_app
+        mcp_app = MCPCompatApp(
+            sse_app=legacy_sse_app,
+            streamable_http_app=streamable_http_app,
+        )
+
+        app = Starlette(debug=True, lifespan=self._app_lifespan)
+        app.state.store = self._store
+        app.state.config = self._config
+        dev_origin = dashboard_dev_origin(self._config)
+        if dev_origin:
+            app.add_middleware(
+                CORSMiddleware,
+                allow_origins=[dev_origin],
+                allow_credentials=True,
+                allow_methods=["*"],
+                allow_headers=["*"],
+            )
+
+        # Observability middleware
+        app.add_middleware(GlobalExceptionMiddleware)
+        app.add_middleware(CorrelationIdMiddleware)
+        app.add_middleware(AccessLogMiddleware)
+
+        if self._middleware and self._middleware._auth:
+            app.add_middleware(SSEAuthMiddleware, auth_service=self._middleware._auth)
+
+        for route in self._extra_routes:
+            app.router.routes.append(route)
+
+        app.add_route(
+            "/.well-known/oauth-protected-resource",
+            self._oauth_protected_resource_metadata,
+            methods=["GET"],
+        )
+        app.add_route(
+            "/.well-known/oauth-protected-resource/sse",
+            self._oauth_protected_resource_metadata,
+            methods=["GET"],
+        )
+        app.add_route(
+            "/.well-known/oauth-protected-resource/mcp",
+            self._oauth_protected_resource_metadata,
+            methods=["GET"],
+        )
+
+        app.mount("/", mcp_app)
+        return app
+
+    async def run(self) -> None:
+        """Custom run loop to handle starlette app with middleware."""
+        app = self.build_starlette_app()
+
+        config = uvicorn.Config(
+            app,
+            host=self._config.server.host,
+            port=self._config.server.port,
+            log_level="info",
+        )
+        server = uvicorn.Server(config)
+        await server.serve()

minder/transport/stdio.py

@@ -0,0 +1,29 @@
+import os
+
+from minder.auth.service import AuthService
+from minder.config import MinderConfig
+from minder.store.interfaces import ICacheProvider, IOperationalStore
+from minder.transport.base import BaseTransport
+
+
+class StdioTransport(BaseTransport):
+    transport_name = "stdio"
+
+    def __init__(
+        self,
+        *,
+        config: MinderConfig,
+        store: IOperationalStore | None = None,
+        auth_service: AuthService | None = None,
+        cache_provider: ICacheProvider,
+    ) -> None:
+        super().__init__(
+            config=config, 
+            auth_service=auth_service, 
+            cache_provider=cache_provider,
+            store=store,
+        )
+
+    def _default_client_key(self) -> str | None:
+        client_key = os.getenv("MINDER_CLIENT_API_KEY", "").strip()
+        return client_key or None

minder_cli-0.2.0.dist-info/METADATA

@@ -0,0 +1,318 @@
+Metadata-Version: 2.4
+Name: minder-cli
+Version: 0.2.0
+Summary: Minder is an AI MCP server for manage your LLM flow development and memory of AI agent.
+Project-URL: Homepage, https://github.com/hiimtrung/minder
+Project-URL: Repository, https://github.com/hiimtrung/minder
+Project-URL: Documentation, https://github.com/hiimtrung/minder/tree/main/docs
+License-File: LICENSE
+Keywords: ai,cli,code-search,mcp,workflow
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.14
+Requires-Dist: fastapi>=0.136.0
+Requires-Dist: httpx>=0.27.0
+Provides-Extra: server
+Requires-Dist: aiosqlite>=0.21.0; extra == 'server'
+Requires-Dist: langgraph>=1.1.4; extra == 'server'
+Requires-Dist: litellm>=1.83.1; extra == 'server'
+Requires-Dist: llama-cpp-python>=0.3.20; extra == 'server'
+Requires-Dist: mcp>=1.26.0; extra == 'server'
+Requires-Dist: motor>=3.7.0; extra == 'server'
+Requires-Dist: passlib[bcrypt]>=1.7.4; extra == 'server'
+Requires-Dist: prometheus-client>=0.24.1; extra == 'server'
+Requires-Dist: pydantic-settings[toml]>=2.13.1; extra == 'server'
+Requires-Dist: pydantic>=2.12.5; extra == 'server'
+Requires-Dist: pyjwt>=2.12.1; extra == 'server'
+Requires-Dist: pymilvus>=2.5.0; extra == 'server'
+Requires-Dist: redis[hiredis]>=6.0.0; extra == 'server'
+Requires-Dist: sqlalchemy[asyncio]>=2.0.48; extra == 'server'
+Description-Content-Type: text/markdown
+
+# Minder
+
+<p align="center">
+  <img src="favicon.png" width="220" alt="Minder logo" />
+</p>
+
+<p align="center">
+  <strong>Self-hosted MCP platform for repo-aware engineering intelligence.</strong><br/>
+  Search smarter, govern workflows, persist memory, onboard clients, and run over <code>SSE</code> or <code>stdio</code>.
+</p>
+
+---
+
+## Why Minder
+
+- Repository-aware retrieval across code, docs, and historical errors.
+- Workflow governance that keeps delivery phases explicit and auditable.
+- Persistent memory and session context for long-running engineering tasks.
+- Built-in admin dashboard plus API-first client onboarding.
+- Single platform for Codex, Copilot-style MCP clients, Claude Desktop, and CLI automation.
+
+---
+
+## Quick Start (Local in Minutes)
+
+### 1) Download GGUF models
+
+```bash
+./scripts/download_models.sh
+```
+
+Models are saved to `~/.minder/models`.
+
+### 2) Prepare environment
+
+```bash
+cp .env.example .env
+cp src/dashboard/.env.example src/dashboard/.env
+```
+
+Default local layout:
+- Minder API/Gateway: `http://localhost:8800`
+- Dashboard dev server: `http://localhost:8808/dashboard`
+
+### 3) Start infra services
+
+```bash
+docker compose -f docker/docker-compose.local.yml up -d
+```
+
+This starts MongoDB, Redis, Milvus Standalone (plus etcd + MinIO).
+
+### 4) Run backend
+
+```bash
+PYTHONPATH=src UV_CACHE_DIR=.uv-cache uv run python -m minder.server
+```
+
+### 5) Run dashboard (dev mode)
+
+```bash
+cd src/dashboard
+bun install
+bun run dev
+```
+
+Or build static assets for serving via Minder on `:8800`:
+
+```bash
+cd src/dashboard && bun run build
+```
+
+### 6) Bootstrap first admin
+
+Open [http://localhost:8800/dashboard/setup](http://localhost:8800/dashboard/setup) and create the first admin.
+
+Minder returns the bootstrap API key (`mk_...`) exactly once. Save it immediately.
+
+### 7) Sign in
+
+Open [http://localhost:8800/dashboard/login](http://localhost:8800/dashboard/login) and authenticate with the `mk_...` key.
+
+---
+
+## System Architecture
+
+```mermaid
+flowchart TB
+    Browser["Browser Admin"] --> Gateway["Gateway :8800"]
+    MCP["Codex · Copilot · Claude Desktop · stdio"] --> Gateway
+
+    Gateway --> Dashboard["Astro Dashboard\\n/dashboard/*"]
+    Gateway --> AdminAPI["Admin HTTP\\n/v1/admin/*"]
+    Gateway --> AuthAPI["Token Exchange · Gateway Test\\n/v1/auth/* · /v1/gateway/*"]
+    Gateway --> MCPTools["MCP Tool Surface\\nSSE · stdio"]
+
+    AdminAPI & AuthAPI & MCPTools --> UseCases["Application Use Cases"]
+
+    UseCases --> Auth["Auth · RBAC · Rate Limiting"]
+    UseCases --> Services["Workflow · Memory · Session · Query"]
+
+    Services --> Mongo["MongoDB"]
+    Services --> Redis["Redis"]
+    Services --> Milvus["Milvus Standalone"]
+    Services --> LLM["Gemma GGUF\\nllama-cpp-python"]
+```
+
+### Clean runtime layers
+
+```text
+Presentation   -> src/minder/presentation/http/admin   (HTTP routes, DTOs)
+                 src/dashboard                         (Astro admin console)
+Application    -> src/minder/application/admin         (use cases)
+Domain         -> src/minder/models                    (entities, value objects)
+Infrastructure -> src/minder/store                     (MongoDB, Milvus, Redis adapters)
+                 src/minder/auth                       (principals, middleware, rate limiter)
+                 src/minder/graph                      (LangGraph pipeline, nodes)
+```
+
+### Runtime stack
+
+| Service | Role | Default Port |
+| --- | --- | --- |
+| Minder API | MCP server, admin HTTP, token exchange | `8800` |
+| Astro Dashboard | Admin console (dev standalone, prod proxied) | `8808` (dev) |
+| MongoDB 7 | Users, clients, sessions | `27017` |
+| Redis 7 | Cache, rate limiting, token sessions | `6379` |
+| Milvus Standalone | Vector index for docs/code/errors | `19530` |
+
+---
+
+## MCP Tool Surface
+
+| Tool | Description |
+| --- | --- |
+| `minder_query` | End-to-end RAG pipeline: retrieve + reason + verify |
+| `minder_search_code` | Semantic code retrieval across indexed repositories |
+| `minder_search_errors` | Error retrieval with troubleshooting context |
+| `minder_search` | General semantic search over project knowledge |
+| `minder_memory_recall` | Retrieve persisted memory entries |
+| `minder_workflow_get` | Read current workflow state |
+| `minder_workflow_step` | Move workflow to the next step |
+
+---
+
+## CLI Distribution
+
+Install from PyPI:
+
+```bash
+uv tool install minder
+# or
+pipx install minder
+```
+
+Typical flow:
+
+```bash
+minder login --client-key mkc_your_client_key --server-url http://localhost:8800/sse
+minder install-ide --target vscode --target claude-code
+minder sync --repo-id <repository-uuid>
+```
+
+Highlights:
+- `minder install-ide` scaffolds repo-local MCP/instruction assets for VS Code, Cursor, and Claude Code.
+- `minder sync` auto-detects cross-repo `branch_relationships` via `.gitmodules` and optional `.minder/branch-topology.toml`.
+
+Update commands:
+
+```bash
+minder check-update
+minder self-update --component cli
+minder self-update --component server
+```
+
+`self-update --component server` uses PowerShell installer on Windows and bash installer on macOS/Linux.
+
+---
+
+## Operator Playbooks
+
+### Onboard an MCP client
+
+1. Open **Client Registry** in dashboard.
+2. Create client with name, slug, tool scopes, repo scopes.
+3. Save the issued key (`mkc_...`) immediately (shown once).
+4. Use the key via:
+
+| Transport | Auth Mechanism |
+| --- | --- |
+| SSE | `X-Minder-Client-Key: mkc_...` header |
+| stdio | `MINDER_CLIENT_API_KEY=mkc_...` env var |
+| OAuth-style | `POST /v1/auth/token-exchange` with client key |
+
+### Rotate or revoke key
+
+From client detail page:
+- **Rotate Key**: issues new key and invalidates old key.
+- **Revoke**: permanently blocks client.
+
+Both actions are audit logged.
+
+### Recover admin access
+
+```bash
+PYTHONPATH=src UV_CACHE_DIR=.uv-cache uv run python scripts/reset_admin_api_key.py \
+  --username <admin-username>
+```
+
+### Production deployment
+
+```bash
+docker compose -f docker/docker-compose.yml up -d
+```
+
+Production topology runs `gateway`, `minder-api`, and `dashboard` behind a single public origin (`:8800`).
+
+---
+
+## Configuration
+
+Config load order:
+1. `minder.toml`
+2. `MINDER_` environment overrides
+
+Key variables:
+
+| Variable | Default | Purpose |
+| --- | --- | --- |
+| `MINDER_SERVER__PORT` | `8800` | HTTP listen port |
+| `MINDER_MONGODB__URI` | `mongodb://localhost:27017` | MongoDB URI |
+| `MINDER_REDIS__URI` | `redis://localhost:6379/0` | Redis URI |
+| `MINDER_VECTOR_STORE__URI` | `http://localhost:19530` | Milvus endpoint |
+| `MINDER_LLM__MODEL_PATH` | `~/.minder/models/gemma-4-e2b-it-Q8_0.gguf` | Local LLM model |
+| `MINDER_EMBEDDING__MODEL_PATH` | `~/.minder/models/embeddinggemma-300M-Q8_0.gguf` | Embedding model |
+| `MINDER_CACHE__PROVIDER` | `redis` | `redis` or `lru` |
+| `MINDER_WORKFLOW__ORCHESTRATION_RUNTIME` | `langgraph` | `langgraph` or `simple` |
+
+---
+
+## Prerequisites
+
+| Requirement | Version |
+| --- | --- |
+| Python | `>= 3.14` |
+| uv | latest |
+| Docker + Compose | v2+ |
+| Bun | `1.2.21+` (dashboard dev only) |
+
+---
+
+## Testing
+
+Run all tests:
+
+```bash
+UV_CACHE_DIR=.uv-cache uv run pytest
+```
+
+Phase-specific gates:
+
+```bash
+uv run pytest tests/integration/test_phase3_gate.py
+uv run pytest tests/e2e/test_phase4_gateway_auth.py
+uv run pytest tests/integration/test_phase4_3_console_gate.py
+```
+
+Note: integration tests that hit Milvus/MongoDB/Redis require Docker services running.
+
+---
+
+## Documentation Index
+
+- [System Design](docs/system-design.md)
+- [Project Plan](docs/PLAN.md)
+- [Project Progress](docs/PROJECT_PROGRESS.md)
+- [Task Breakdown](docs/TASK_BREAKDOWN.md)
+- [Local Setup Guide](docs/guides/local-setup.md)
+- [Minder CLI Guide](docs/guides/minder-cli.md)
+- [Admin & Client Onboarding](docs/guides/admin-client-onboarding.md)
+- [Production Deployment](docs/guides/production-deployment.md)
+- [Gateway Auth Design](docs/design/mcp-gateway-auth-dashboard.md)