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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docforge-cli
-Version: 0.3.0
+Version: 0.4.1
 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.1}/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.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "docforge-cli"
-version = "0.3.0"
+version = "0.4.1"
 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.1}/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.1}/src/docforge/cli.py

@@ -8,6 +8,8 @@ from pathlib import Path
 
 import typer
 
+from docforge.remote_client import AuthName
+
 app = typer.Typer(
     help="Forge searchable context from Confluence and git repos for AI coding assistants.",
 )
@@ -117,10 +119,34 @@ 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: AuthName = typer.Option(
+        AuthName.none,
+        "--auth",
+        help="Auth provider for --remote-api",
+        envvar="DOCFORGE_AUTH",
+    ),
+) -> None:
+    """Run the MCP server (or FastAPI API with --api, or remote-backed MCP with --remote-api)."""
     _setup_logging()
-    if api:
+    if remote_api and api:
+        typer.echo("Error: --api and --remote-api are mutually exclusive.", err=True)
+        raise typer.Exit(1)
+    if auth is not AuthName.none and not remote_api:
+        typer.echo("Warning: --auth has no effect without --remote-api.", err=True)
+
+    if remote_api:
+        from docforge.remote_client import run_remote_mcp
+
+        run_remote_mcp(url=remote_api, auth_name=auth)
+    elif api:
         import uvicorn
 
         from docforge.api import app as fastapi_app

{docforge_cli-0.3.0 → docforge_cli-0.4.1}/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.3.0 → docforge_cli-0.4.1}/src/docforge/mcp_server.py

@@ -49,6 +49,32 @@ def _get_embedder() -> EmbedderProtocol:
     return _embedder
 
 
+def format_search_results_markdown(
+    results: list[dict],
+    *,
+    empty_message: str = "No documentation found matching your query.",
+) -> str:
+    """Render a list of search-result dicts as the canonical Markdown shape.
+
+    Each result must have keys: similarity, source_title, source_url, text.
+    Optional: section_title, source_tags.
+    """
+    if not results:
+        return empty_message
+
+    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)
+
+
 @mcp.tool()
 async def search_documentation(
     query: Annotated[str, Field(max_length=8000)],
@@ -115,31 +141,23 @@ async def search_documentation(
 
     await log_query(pool, user_name, team_name, area_name, query, len(rows))
 
-    if not rows:
-        return (
+    return format_search_results_markdown(
+        [
+            {
+                "similarity": row["similarity"],
+                "source_title": row["source_title"],
+                "source_url": row["source_url"],
+                "section_title": row["section_title"],
+                "source_tags": list(row["source_tags"] or []),
+                "text": row["text"],
+            }
+            for row in rows
+        ],
+        empty_message=(
             "No documentation found matching your query. "
             "The index may be empty -- run `python -m docforge ingest` to populate it."
-        )
-
-    parts: list[str] = []
-    for i, row in enumerate(rows, 1):
-        similarity = row["similarity"]
-        source = row["source_title"]
-        url = row["source_url"]
-        section = row["section_title"]
-        text = row["text"]
-        tags = list(row["source_tags"] or [])
-
-        header = f"**Result {i}** (relevance: {similarity:.2f}) — {source}"
-        if section:
-            header += f" > {section}"
-        header += f"\nSource: {url}"
-        if tags:
-            header += f"\nTags: {', '.join(tags)}"
-
-        parts.append(f"{header}\n\n{text}")
-
-    return "\n\n---\n\n".join(parts)
+        ),
+    )
 
 
 @mcp.tool()

docforge_cli-0.4.1/src/docforge/remote_client.py

@@ -0,0 +1,213 @@
+"""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 enum import Enum
+from typing import Protocol
+
+import httpx
+from fastmcp import FastMCP
+
+
+class AuthName(str, Enum):
+    """Selectable auth providers for the --remote-api mode."""
+
+    none = "none"
+    bearer = "bearer"
+    azure = "azure"
+
+
+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: AuthName | str) -> AuthProvider:
+    """Return an AuthProvider instance for the given name."""
+    try:
+        name = AuthName(name) if isinstance(name, str) else name
+    except ValueError as e:
+        raise ValueError(f"Unknown auth provider: {name!r}. Valid: none, bearer, azure.") from e
+    if name is AuthName.none:
+        return NoneAuth()
+    if name is AuthName.bearer:
+        return BearerAuth()
+    if name is AuthName.azure:
+        return AzureAuth()
+    raise ValueError(f"Unknown auth provider: {name!r}.")
+
+
+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
+        self._client: httpx.AsyncClient | None = None
+
+    async def _ensure_client(self) -> httpx.AsyncClient:
+        if self._client is None:
+            self._client = httpx.AsyncClient(transport=self._transport, timeout=30.0)
+        return self._client
+
+    async def aclose(self) -> None:
+        if self._client is not None:
+            await self._client.aclose()
+            self._client = None
+
+    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 _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: dict[str, object] | None = None,
+    ) -> httpx.Response | str:
+        """Perform an HTTP request with auth and uniform error handling.
+
+        Returns the Response on 2xx; an already-formatted error string otherwise.
+        """
+        try:
+            headers = await self._auth.headers()
+        except Exception as e:
+            return f"Auth provider error: {e}"
+
+        client = await self._ensure_client()
+        try:
+            resp = await client.request(method, f"{self._url}{path}", json=json, 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]}"
+        return resp
+
+    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())
+        result = await self._request("POST", "/search", json=body)
+        if isinstance(result, str):
+            return result
+
+        from docforge.mcp_server import format_search_results_markdown
+
+        data = result.json()
+        return format_search_results_markdown(data.get("results", []))
+
+    async def list_sources(self) -> str:
+        """List indexed sources from the remote API."""
+        result = await self._request("GET", "/sources")
+        if isinstance(result, str):
+            return result
+
+        data = result.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: AuthName | str = AuthName.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.1}/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.1}/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.1
 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.1}/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.1}/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