docforge-cli 0.3.0__tar.gz → 0.4.0__tar.gz

{docforge_cli-0.3.0 → docforge_cli-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docforge-cli
-Version: 0.3.0
+Version: 0.4.0
 Summary: Forge searchable context from Confluence and git repos for AI coding assistants
 License: MIT
 Project-URL: Homepage, https://GranatenUdo.github.io/docforge/
@@ -34,6 +34,9 @@ Provides-Extra: entra
 Requires-Dist: fastapi-azure-auth<6.0,>=5.0; extra == "entra"
 Requires-Dist: azure-identity<2.0,>=1.19; extra == "entra"
 Requires-Dist: aiohttp<4.0,>=3.10; extra == "entra"
+Provides-Extra: azure
+Requires-Dist: azure-identity<2.0,>=1.19; extra == "azure"
+Requires-Dist: aiohttp<4.0,>=3.10; extra == "azure"
 Dynamic: license-file
 
 # docforge
@@ -143,6 +146,39 @@ For team-wide use, deploy the search API to Azure (~$90/month at default SKUs wi
 
 See [`deploy/azure/`](deploy/azure/) for Bicep templates and a full cost breakdown.
 
+## Use a hosted instance (no local DB required)
+
+If your team already operates a docforge deployment and you only want to *use* it from your editor (Claude Code, etc.), you don't need to clone, ingest, or run Postgres locally:
+
+```bash
+# Generic (no auth)
+pip install docforge-cli
+claude mcp add -s user -e DOCFORGE_API_URL=https://docforge.example.com \
+  docforge -- docforge serve --remote-api $DOCFORGE_API_URL
+
+# Static Bearer token
+pip install docforge-cli
+claude mcp add -s user \
+  -e DOCFORGE_API_URL=https://docforge.example.com \
+  -e DOCFORGE_API_TOKEN=eyJ... \
+  -e DOCFORGE_AUTH=bearer \
+  docforge -- docforge serve --remote-api $DOCFORGE_API_URL --auth bearer
+
+# Entra (Azure AD)
+pip install docforge-cli[azure]
+az login --tenant <your-tenant-id>
+claude mcp add -s user \
+  -e DOCFORGE_API_URL=https://docforge.example.com \
+  -e DOCFORGE_AUDIENCE=api://<app-registration-uri> \
+  -e DOCFORGE_AUTH=azure \
+  -e DOCFORGE_TEAM=your-team \
+  docforge -- docforge serve --remote-api $DOCFORGE_API_URL --auth azure
+```
+
+With `--auth azure`, `user_name` is bound to your Entra JWT subject — you can't (and don't need to) configure it.
+
+`DOCFORGE_TEAM` is optional but recommended for team-tag relevance boosting in search results.
+
 ## Self-hosting / forking
 
 The embedder image bakes the EmbeddingGemma-300M model at build time,

{docforge_cli-0.3.0 → docforge_cli-0.4.0}/README.md

@@ -105,6 +105,39 @@ For team-wide use, deploy the search API to Azure (~$90/month at default SKUs wi
 
 See [`deploy/azure/`](deploy/azure/) for Bicep templates and a full cost breakdown.
 
+## Use a hosted instance (no local DB required)
+
+If your team already operates a docforge deployment and you only want to *use* it from your editor (Claude Code, etc.), you don't need to clone, ingest, or run Postgres locally:
+
+```bash
+# Generic (no auth)
+pip install docforge-cli
+claude mcp add -s user -e DOCFORGE_API_URL=https://docforge.example.com \
+  docforge -- docforge serve --remote-api $DOCFORGE_API_URL
+
+# Static Bearer token
+pip install docforge-cli
+claude mcp add -s user \
+  -e DOCFORGE_API_URL=https://docforge.example.com \
+  -e DOCFORGE_API_TOKEN=eyJ... \
+  -e DOCFORGE_AUTH=bearer \
+  docforge -- docforge serve --remote-api $DOCFORGE_API_URL --auth bearer
+
+# Entra (Azure AD)
+pip install docforge-cli[azure]
+az login --tenant <your-tenant-id>
+claude mcp add -s user \
+  -e DOCFORGE_API_URL=https://docforge.example.com \
+  -e DOCFORGE_AUDIENCE=api://<app-registration-uri> \
+  -e DOCFORGE_AUTH=azure \
+  -e DOCFORGE_TEAM=your-team \
+  docforge -- docforge serve --remote-api $DOCFORGE_API_URL --auth azure
+```
+
+With `--auth azure`, `user_name` is bound to your Entra JWT subject — you can't (and don't need to) configure it.
+
+`DOCFORGE_TEAM` is optional but recommended for team-tag relevance boosting in search results.
+
 ## Self-hosting / forking
 
 The embedder image bakes the EmbeddingGemma-300M model at build time,

{docforge_cli-0.3.0 → docforge_cli-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "docforge-cli"
-version = "0.3.0"
+version = "0.4.0"
 description = "Forge searchable context from Confluence and git repos for AI coding assistants"
 readme = "README.md"
 license = {text = "MIT"}
@@ -49,6 +49,10 @@ entra = [
     # aiohttp is required by azure-identity.aio's async pipeline
     "aiohttp>=3.10,<4.0",
 ]
+azure = [
+    "azure-identity>=1.19,<2.0",
+    "aiohttp>=3.10,<4.0",  # required by azure-identity.aio
+]
 
 [tool.setuptools.packages.find]
 where = ["src"]

{docforge_cli-0.3.0 → docforge_cli-0.4.0}/src/docforge/api.py

@@ -155,8 +155,8 @@ async def _auth_dependency(
 
 class SearchRequest(BaseModel):
     query: str = Field(..., max_length=8000)
-    user_name: str
-    team_name: str
+    user_name: str | None = None
+    team_name: str | None = None
     area_name: str | None = None
     limit: int = Field(5, ge=1, le=50)
 
@@ -203,7 +203,7 @@ async def search(
         logger.error("Embedding failed: %s", e)
         raise HTTPException(status_code=500, detail="Failed to embed query")
 
-    user_tags = [req.team_name] + ([req.area_name] if req.area_name else [])
+    user_tags = [t for t in (req.team_name, req.area_name) if t]
 
     try:
         async with pool.acquire() as conn:
@@ -241,9 +241,10 @@ async def search(
 
     request_ms = int((time.perf_counter() - start) * 1000)
 
+    effective_user_name = user.preferred_username if user else (req.user_name or "anonymous")
     await log_query(
         pool,
-        user.preferred_username if user else req.user_name,
+        effective_user_name,
         req.team_name,
         req.area_name,
         req.query,

{docforge_cli-0.3.0 → docforge_cli-0.4.0}/src/docforge/cli.py

@@ -117,9 +117,31 @@ def search(
 
 
 @app.command()
-def serve(api: bool = typer.Option(False, help="Run FastAPI search API instead of MCP")):
-    """Run the MCP server (or FastAPI API with --api)."""
+def serve(
+    api: bool = typer.Option(False, help="Run FastAPI search API instead of MCP"),
+    remote_api: str | None = typer.Option(
+        None,
+        "--remote-api",
+        help="Run MCP backed by a remote search API at this URL",
+        envvar="DOCFORGE_API_URL",
+    ),
+    auth: str = typer.Option(
+        "none",
+        "--auth",
+        help="Auth provider for --remote-api: none | bearer | azure",
+        envvar="DOCFORGE_AUTH",
+    ),
+) -> None:
+    """Run the MCP server (or FastAPI API with --api, or remote-backed MCP with --remote-api)."""
     _setup_logging()
+    if remote_api:
+        if api:
+            typer.echo("Error: --api and --remote-api are mutually exclusive.", err=True)
+            raise typer.Exit(1)
+        from docforge.remote_client import run_remote_mcp
+
+        run_remote_mcp(url=remote_api, auth_name=auth)
+        return
     if api:
         import uvicorn
 

{docforge_cli-0.3.0 → docforge_cli-0.4.0}/src/docforge/config.py

@@ -104,7 +104,7 @@ class Settings(BaseSettings):
         yml_path = Path("docforge.yml")
         yml_values = {}
         if yml_path.exists():
-            with open(yml_path) as f:
+            with open(yml_path, encoding="utf-8") as f:
                 yml = yaml.safe_load(f) or {}
             # Flatten nested embedding config
             if "embedding" in yml:

docforge_cli-0.4.0/src/docforge/remote_client.py

@@ -0,0 +1,199 @@
+"""MCP server that proxies tool calls to a remote docforge search-api.
+
+Used by `docforge serve --remote-api $URL --auth ...`. See the
+2026-05-08-docforge-remote-api-mode-design.md spec for the full design.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Protocol
+
+import httpx
+from fastmcp import FastMCP
+
+
+class AuthProvider(Protocol):
+    """Async source of HTTP headers attached to each remote request."""
+
+    async def headers(self) -> dict[str, str]: ...
+
+
+class NoneAuth:
+    """No-op auth provider. Returns no headers."""
+
+    async def headers(self) -> dict[str, str]:
+        return {}
+
+
+class BearerAuth:
+    """Static Bearer token from DOCFORGE_API_TOKEN env var."""
+
+    def __init__(self) -> None:
+        token = os.environ.get("DOCFORGE_API_TOKEN", "").strip()
+        if not token:
+            raise RuntimeError("BearerAuth requires DOCFORGE_API_TOKEN env var to be set.")
+        self._token = token
+
+    async def headers(self) -> dict[str, str]:
+        return {"Authorization": f"Bearer {self._token}"}
+
+
+class AzureAuth:
+    """Entra Bearer token via DefaultAzureCredential.
+
+    Requires `pip install docforge-cli[azure]`. Reads target audience
+    from DOCFORGE_AUDIENCE env var.
+    """
+
+    def __init__(self) -> None:
+        try:
+            from azure.identity.aio import DefaultAzureCredential
+        except ImportError as e:
+            raise ImportError("Azure auth requires `pip install docforge-cli[azure]`.") from e
+
+        audience = os.environ.get("DOCFORGE_AUDIENCE", "").strip()
+        if not audience:
+            raise RuntimeError("AzureAuth requires DOCFORGE_AUDIENCE env var to be set.")
+        self._audience = audience
+        self._credential = DefaultAzureCredential()
+
+    async def headers(self) -> dict[str, str]:
+        token = await self._credential.get_token(f"{self._audience}/.default")
+        return {"Authorization": f"Bearer {token.token}"}
+
+
+def make_auth_provider(name: str) -> AuthProvider:
+    """Return an AuthProvider instance for the given name."""
+    if name == "none":
+        return NoneAuth()
+    if name == "bearer":
+        return BearerAuth()
+    if name == "azure":
+        return AzureAuth()
+    raise ValueError(f"Unknown auth provider: {name!r}. Valid: none, bearer, azure.")
+
+
+class RemoteBackend:
+    """Proxy to a remote docforge search-api over HTTP."""
+
+    def __init__(
+        self,
+        *,
+        url: str,
+        auth: AuthProvider,
+        transport: httpx.AsyncBaseTransport | None = None,
+    ) -> None:
+        self._url = url.rstrip("/")
+        self._auth = auth
+        self._transport = transport  # for tests
+
+    def _identity_body(self) -> dict[str, str]:
+        out: dict[str, str] = {}
+        for env_var, body_key in (
+            ("DOCFORGE_USER", "user_name"),
+            ("DOCFORGE_TEAM", "team_name"),
+            ("DOCFORGE_AREA", "area_name"),
+        ):
+            val = os.environ.get(env_var, "").strip()
+            if val:
+                out[body_key] = val
+        return out
+
+    async def search(self, *, query: str, limit: int = 5) -> str:
+        """Search the remote API and return Markdown-formatted results."""
+        body: dict[str, object] = {"query": query, "limit": limit}
+        body.update(self._identity_body())
+        try:
+            headers = await self._auth.headers()
+        except Exception as e:
+            return f"Auth provider error: {e}"
+
+        try:
+            async with httpx.AsyncClient(transport=self._transport, timeout=30.0) as client:
+                resp = await client.post(f"{self._url}/search", json=body, headers=headers)
+        except httpx.ConnectError:
+            return f"Could not reach remote API at {self._url}."
+        except httpx.HTTPError as e:
+            return f"Remote API error: {e}"
+
+        if resp.status_code == 401:
+            return "Auth failed (401). Check DOCFORGE_API_URL and the --auth provider."
+        if 500 <= resp.status_code < 600:
+            return f"Remote API error ({resp.status_code}). Try again in a moment."
+        if resp.status_code != 200:
+            return f"Remote API returned {resp.status_code}: {resp.text[:200]}"
+
+        data = resp.json()
+        results = data.get("results", [])
+        if not results:
+            return "No documentation found matching your query."
+
+        parts: list[str] = []
+        for i, r in enumerate(results, 1):
+            header = f"**Result {i}** (relevance: {r['similarity']:.2f}) -- {r['source_title']}"
+            if r.get("section_title"):
+                header += f" > {r['section_title']}"
+            header += f"\nSource: {r['source_url']}"
+            tags = r.get("source_tags") or []
+            if tags:
+                header += f"\nTags: {', '.join(tags)}"
+            parts.append(f"{header}\n\n{r['text']}")
+        return "\n\n---\n\n".join(parts)
+
+    async def list_sources(self) -> str:
+        """List indexed sources from the remote API."""
+        try:
+            headers = await self._auth.headers()
+        except Exception as e:
+            return f"Auth provider error: {e}"
+
+        try:
+            async with httpx.AsyncClient(transport=self._transport, timeout=10.0) as client:
+                resp = await client.get(f"{self._url}/sources", headers=headers)
+        except httpx.ConnectError:
+            return f"Could not reach remote API at {self._url}."
+        except httpx.HTTPError as e:
+            return f"Remote API error: {e}"
+
+        if resp.status_code == 401:
+            return "Auth failed (401). Check DOCFORGE_API_URL and the --auth provider."
+        if resp.status_code != 200:
+            return f"Remote API returned {resp.status_code}: {resp.text[:200]}"
+
+        data = resp.json()
+        sources = data.get("sources", [])
+        if not sources:
+            return "No sources indexed."
+
+        lines = [f"**{data.get('count', len(sources))} indexed sources:**\n"]
+        for s in sources:
+            lines.append(f"- **{s['title']}** ({s['chunk_count']} chunks, {s['status']})")
+        return "\n".join(lines)
+
+
+INSTRUCTIONS = (
+    "Search across your team's indexed documentation including team responsibilities, "
+    "coding guidelines, architecture standards, and cross-team interfaces. "
+    "Use the search_documentation tool when you need information about other teams, "
+    "shared coding practices, or organizational knowledge."
+)
+
+
+def run_remote_mcp(*, url: str, auth_name: str = "none") -> None:
+    """Run an MCP server proxying tool calls to a remote docforge search-api."""
+    auth = make_auth_provider(auth_name)
+    backend = RemoteBackend(url=url, auth=auth)
+    mcp = FastMCP("docforge", instructions=INSTRUCTIONS)
+
+    @mcp.tool()
+    async def search_documentation(query: str, limit: int = 5) -> str:
+        """Search across indexed documentation from Confluence pages and git repos."""
+        return await backend.search(query=query, limit=limit)
+
+    @mcp.tool()
+    async def list_sources() -> str:
+        """List all documentation sources currently indexed."""
+        return await backend.list_sources()
+
+    mcp.run()

{docforge_cli-0.3.0 → docforge_cli-0.4.0}/src/docforge/sources.py

@@ -41,6 +41,6 @@ class SourcesFile(BaseModel):
 
 def load_sources(path: str | Path) -> list[SourceConfig]:
     """Load source configurations from a YAML file."""
-    with open(path) as f:
+    with open(path, encoding="utf-8") as f:
         data = yaml.safe_load(f)
     return SourcesFile.model_validate(data).sources

{docforge_cli-0.3.0 → docforge_cli-0.4.0}/src/docforge_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docforge-cli
-Version: 0.3.0
+Version: 0.4.0
 Summary: Forge searchable context from Confluence and git repos for AI coding assistants
 License: MIT
 Project-URL: Homepage, https://GranatenUdo.github.io/docforge/
@@ -34,6 +34,9 @@ Provides-Extra: entra
 Requires-Dist: fastapi-azure-auth<6.0,>=5.0; extra == "entra"
 Requires-Dist: azure-identity<2.0,>=1.19; extra == "entra"
 Requires-Dist: aiohttp<4.0,>=3.10; extra == "entra"
+Provides-Extra: azure
+Requires-Dist: azure-identity<2.0,>=1.19; extra == "azure"
+Requires-Dist: aiohttp<4.0,>=3.10; extra == "azure"
 Dynamic: license-file
 
 # docforge
@@ -143,6 +146,39 @@ For team-wide use, deploy the search API to Azure (~$90/month at default SKUs wi
 
 See [`deploy/azure/`](deploy/azure/) for Bicep templates and a full cost breakdown.
 
+## Use a hosted instance (no local DB required)
+
+If your team already operates a docforge deployment and you only want to *use* it from your editor (Claude Code, etc.), you don't need to clone, ingest, or run Postgres locally:
+
+```bash
+# Generic (no auth)
+pip install docforge-cli
+claude mcp add -s user -e DOCFORGE_API_URL=https://docforge.example.com \
+  docforge -- docforge serve --remote-api $DOCFORGE_API_URL
+
+# Static Bearer token
+pip install docforge-cli
+claude mcp add -s user \
+  -e DOCFORGE_API_URL=https://docforge.example.com \
+  -e DOCFORGE_API_TOKEN=eyJ... \
+  -e DOCFORGE_AUTH=bearer \
+  docforge -- docforge serve --remote-api $DOCFORGE_API_URL --auth bearer
+
+# Entra (Azure AD)
+pip install docforge-cli[azure]
+az login --tenant <your-tenant-id>
+claude mcp add -s user \
+  -e DOCFORGE_API_URL=https://docforge.example.com \
+  -e DOCFORGE_AUDIENCE=api://<app-registration-uri> \
+  -e DOCFORGE_AUTH=azure \
+  -e DOCFORGE_TEAM=your-team \
+  docforge -- docforge serve --remote-api $DOCFORGE_API_URL --auth azure
+```
+
+With `--auth azure`, `user_name` is bound to your Entra JWT subject — you can't (and don't need to) configure it.
+
+`DOCFORGE_TEAM` is optional but recommended for team-tag relevance boosting in search results.
+
 ## Self-hosting / forking
 
 The embedder image bakes the EmbeddingGemma-300M model at build time,

{docforge_cli-0.3.0 → docforge_cli-0.4.0}/src/docforge_cli.egg-info/SOURCES.txt

@@ -13,6 +13,7 @@ src/docforge/lint.py
 src/docforge/mcp_server.py
 src/docforge/query_log.py
 src/docforge/ranking.py
+src/docforge/remote_client.py
 src/docforge/sources.py
 src/docforge/crawlers/__init__.py
 src/docforge/crawlers/confluence.py

{docforge_cli-0.3.0 → docforge_cli-0.4.0}/src/docforge_cli.egg-info/requires.txt

@@ -12,6 +12,10 @@ fastapi<1.0,>=0.115
 uvicorn<1.0,>=0.34
 numpy<3.0,>=1.26
 
+[azure]
+azure-identity<2.0,>=1.19
+aiohttp<4.0,>=3.10
+
 [dev]
 pytest<10.0,>=9.0
 pytest-asyncio<2.0,>=1.0