afs-server 0.1.0__tar.gz

afs_server-0.1.0/.gitignore

@@ -0,0 +1,41 @@
+# --- OS / editor ---
+.DS_Store
+Thumbs.db
+*.swp
+.idea/
+.vscode/
+
+# --- Python (packages land in M0+) ---
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+.uv/
+*.egg-info/
+.ruff_cache/
+.pytest_cache/
+.mypy_cache/
+.ty_cache/
+dist/
+build/
+
+# --- Node (workers/mcp-edge lands later) ---
+node_modules/
+npm-debug.log*
+
+# --- Secrets / local env ---
+.env
+.env.*
+!.env.example
+*.secret.*
+
+# --- Terraform ---
+# Detailed Terraform ignores live in terraform/.gitignore; these catch any
+# stray state/plan artifacts produced outside that tree.
+*.tfstate
+*.tfstate.*
+*.tfplan
+.terraform/
+
+# Agent worktrees (isolated background-agent checkouts)
+.claude/worktrees/

afs_server-0.1.0/PKG-INFO

@@ -0,0 +1,76 @@
+Metadata-Version: 2.4
+Name: afs-server
+Version: 0.1.0
+Summary: agentic-fs server: stores, services, REST + MCP. Implements the afs-core contracts.
+Project-URL: Homepage, https://github.com/vivekkhimani/agentic-fs
+Project-URL: Repository, https://github.com/vivekkhimani/agentic-fs
+Project-URL: Issues, https://github.com/vivekkhimani/agentic-fs/issues
+Author-email: Vivek Khimani <vivekkhimani07@gmail.com>
+License-Expression: Apache-2.0
+Keywords: agentic-fs,agents,dynamodb,fastapi,filesystem,mcp,s3
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: FastAPI
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: afs-core
+Requires-Dist: boto3>=1.34
+Requires-Dist: fastapi>=0.115
+Requires-Dist: fastmcp>=2
+Requires-Dist: pydantic-settings>=2.2
+Requires-Dist: uvicorn[standard]>=0.30
+Provides-Extra: postgres
+Provides-Extra: search
+Description-Content-Type: text/markdown
+
+# afs-server
+
+The agentic-fs service: the concrete backends (stores, search, extraction), the
+services, and the REST + MCP surface. Implements the `afs-core` contracts.
+
+## Status
+
+Store layer (in progress):
+
+- `afs_server.settings` — `AFS_*` env config; every swappable layer is selected
+  by a backend *name* and every AWS-shaped backend takes an `endpoint_url`
+  override.
+- `afs_server.stores` — the **store registry**: `get_object_store(settings)`
+  selects a builtin or an installed plugin (`afs.object_stores` entry-point group).
+- `afs_server.stores.objects_s3.S3ObjectStore` — the S3 `ObjectStore`. Because it
+  speaks plain S3, it *is* your store for any S3-compatible endpoint (MinIO,
+  Cloudflare R2, Wasabi, Backblaze B2) via `AFS_S3_ENDPOINT_URL` — no code change.
+- `afs_server.stores.catalog_dynamodb.DynamoDBCatalogStore` — the DynamoDB
+  `CatalogStore` over the single-table schema (`AFS_DYNAMODB_ENDPOINT_URL` points
+  at DynamoDB Local for dev).
+
+Both stores are certified by the afs-core conformance kits via `moto`.
+
+- `afs_server.services.FsService` — the read path (`list` / `stat` / ranged
+  `read`) over the stores, with scope + namespace enforcement and 404-not-403
+  misses.
+- `afs_server.app` — the FastAPI app: `/v1/healthz`, `/readyz`, `/me`, and
+  `fs/{ns}/{entries,stat,doc}`; dev auth (static principal, never prod); every
+  `AfsError` rendered as RFC 9457 `problem+json`.
+- `afs_server.mcp` — the MCP surface mounted at `/mcp` (FastMCP): `whoami`,
+  `fs_list`, `fs_stat`, `fs_read` over the *same* `FsService` (in-process, no HTTP
+  self-calls). The full middleware chain + remaining tools land with their slices.
+
+The image (`../../Dockerfile`) runs this app on Lambda / Fargate / locally;
+`make dev` from the repo root runs it against MinIO + DynamoDB Local. Coming
+next: the MCP mount (shares `FsService` in-process).
+
+## Swapping a backend (plug-and-play)
+
+See [`docs/swap-guides/`](../../docs/swap-guides/). In short: S3-compatible
+storage needs only an env var; anything else implements the `ObjectStore`
+Protocol, registers an entry point, and certifies against
+`afs_core.testing.ObjectStoreConformance`.
+
+## Develop
+
+```bash
+uv sync
+uv run pytest packages/afs-server     # conformance kits run against moto
+```

afs_server-0.1.0/README.md

@@ -0,0 +1,50 @@
+# afs-server
+
+The agentic-fs service: the concrete backends (stores, search, extraction), the
+services, and the REST + MCP surface. Implements the `afs-core` contracts.
+
+## Status
+
+Store layer (in progress):
+
+- `afs_server.settings` — `AFS_*` env config; every swappable layer is selected
+  by a backend *name* and every AWS-shaped backend takes an `endpoint_url`
+  override.
+- `afs_server.stores` — the **store registry**: `get_object_store(settings)`
+  selects a builtin or an installed plugin (`afs.object_stores` entry-point group).
+- `afs_server.stores.objects_s3.S3ObjectStore` — the S3 `ObjectStore`. Because it
+  speaks plain S3, it *is* your store for any S3-compatible endpoint (MinIO,
+  Cloudflare R2, Wasabi, Backblaze B2) via `AFS_S3_ENDPOINT_URL` — no code change.
+- `afs_server.stores.catalog_dynamodb.DynamoDBCatalogStore` — the DynamoDB
+  `CatalogStore` over the single-table schema (`AFS_DYNAMODB_ENDPOINT_URL` points
+  at DynamoDB Local for dev).
+
+Both stores are certified by the afs-core conformance kits via `moto`.
+
+- `afs_server.services.FsService` — the read path (`list` / `stat` / ranged
+  `read`) over the stores, with scope + namespace enforcement and 404-not-403
+  misses.
+- `afs_server.app` — the FastAPI app: `/v1/healthz`, `/readyz`, `/me`, and
+  `fs/{ns}/{entries,stat,doc}`; dev auth (static principal, never prod); every
+  `AfsError` rendered as RFC 9457 `problem+json`.
+- `afs_server.mcp` — the MCP surface mounted at `/mcp` (FastMCP): `whoami`,
+  `fs_list`, `fs_stat`, `fs_read` over the *same* `FsService` (in-process, no HTTP
+  self-calls). The full middleware chain + remaining tools land with their slices.
+
+The image (`../../Dockerfile`) runs this app on Lambda / Fargate / locally;
+`make dev` from the repo root runs it against MinIO + DynamoDB Local. Coming
+next: the MCP mount (shares `FsService` in-process).
+
+## Swapping a backend (plug-and-play)
+
+See [`docs/swap-guides/`](../../docs/swap-guides/). In short: S3-compatible
+storage needs only an env var; anything else implements the `ObjectStore`
+Protocol, registers an entry point, and certifies against
+`afs_core.testing.ObjectStoreConformance`.
+
+## Develop
+
+```bash
+uv sync
+uv run pytest packages/afs-server     # conformance kits run against moto
+```

afs_server-0.1.0/pyproject.toml

@@ -0,0 +1,55 @@
+[project]
+name = "afs-server"
+version = "0.1.0"
+description = "agentic-fs server: stores, services, REST + MCP. Implements the afs-core contracts."
+readme = "README.md"
+requires-python = ">=3.12"
+license = "Apache-2.0"
+authors = [{ name = "Vivek Khimani", email = "vivekkhimani07@gmail.com" }]
+keywords = [
+    "agentic-fs",
+    "agents",
+    "mcp",
+    "fastapi",
+    "s3",
+    "dynamodb",
+    "filesystem",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3.12",
+    "Typing :: Typed",
+    "Framework :: FastAPI",
+]
+dependencies = [
+    "afs-core",
+    "boto3>=1.34",
+    "pydantic-settings>=2.2",
+    "fastapi>=0.115",
+    "uvicorn[standard]>=0.30",
+    "fastmcp>=2",
+]
+
+[project.optional-dependencies]
+# Reserved for future backends. Intentionally empty until the dependencies
+# exist — declaring the names now keeps the install surface stable.
+# TODO: add the Postgres catalog backend deps when that store lands.
+postgres = []
+# TODO: add the search/vector backend deps when that store lands.
+search = []
+
+[project.urls]
+Homepage = "https://github.com/vivekkhimani/agentic-fs"
+Repository = "https://github.com/vivekkhimani/agentic-fs"
+Issues = "https://github.com/vivekkhimani/agentic-fs/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/afs_server"]
+
+[tool.uv.sources]
+afs-core = { workspace = true }

afs_server-0.1.0/src/afs_server/__init__.py

@@ -0,0 +1,3 @@
+"""agentic-fs server: stores, services, REST + MCP — implements the afs-core contracts."""
+
+__version__ = "0.1.0"

afs_server-0.1.0/src/afs_server/app.py

@@ -0,0 +1,75 @@
+"""ASGI application factory.
+
+Assembles the REST surface + the MCP mount (sharing one ``FsService`` in-process,
+no HTTP self-calls), wires the configured stores, and renders every ``AfsError``
+as an RFC 9457 ``application/problem+json`` envelope.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI, Request
+from fastapi.responses import JSONResponse
+
+from afs_core.errors import AfsError
+from afs_server import __version__
+from afs_server.extraction import build_pipeline
+from afs_server.mcp import build_mcp
+from afs_server.routers import fs, ingest, meta
+from afs_server.services import FsService
+from afs_server.settings import load_settings
+from afs_server.stores import get_catalog_store, get_object_store
+
+logger = logging.getLogger("afs_server")
+
+
+async def _afs_error_handler(request: Request, exc: AfsError) -> JSONResponse:
+    return JSONResponse(
+        status_code=exc.http_status,
+        content=exc.to_problem(instance=request.url.path),
+        media_type="application/problem+json",
+    )
+
+
+def create_app() -> FastAPI:
+    settings = load_settings()
+    # Stores are lazy (no I/O / credentials at construction), so we can build the
+    # service + MCP server now and share the service between REST and MCP.
+    catalog = get_catalog_store(settings)
+    objects = get_object_store(settings)
+    fs_service = FsService(catalog, objects)
+    extraction_pipeline = build_pipeline()
+
+    mcp_app = build_mcp(fs_service, settings).http_app(path="/")
+
+    @asynccontextmanager
+    async def lifespan(app: FastAPI) -> AsyncIterator[None]:
+        app.state.settings = settings
+        app.state.catalog = catalog
+        app.state.objects = objects
+        app.state.extraction_pipeline = extraction_pipeline
+        logger.info(
+            "afs-server %s started (object_store=%s, catalog=%s, auth=%s)",
+            __version__,
+            settings.object_store_backend,
+            settings.catalog_backend,
+            settings.auth_mode,
+        )
+        # The MCP session manager runs under its own lifespan — nest it so the
+        # mounted /mcp app works (Starlette does not propagate sub-app lifespans).
+        async with mcp_app.lifespan(app):
+            yield
+
+    app = FastAPI(title="agentic-fs", version=__version__, lifespan=lifespan)
+    app.add_exception_handler(AfsError, _afs_error_handler)  # type: ignore[arg-type]
+    app.include_router(meta.router)
+    app.include_router(fs.router)
+    app.include_router(ingest.router)
+    app.mount("/mcp", mcp_app)
+    return app
+
+
+app = create_app()

afs_server-0.1.0/src/afs_server/auth.py

@@ -0,0 +1,70 @@
+"""Authentication → a resolved tenant context.
+
+This slice ships **dev auth only**: a static local principal selected when
+``AFS_AUTH_MODE=dev``. Any other mode fails closed (401) until the OAuth 2.1
+resource server lands — so a misconfigured deployment never silently serves data
+with no identity. No tokens or secrets are baked into the image.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+from afs_core.errors import InsufficientScopeError, UnauthenticatedError
+
+if TYPE_CHECKING:
+    from afs_server.settings import Settings
+
+logger = logging.getLogger("afs_server.auth")
+
+# Full scope set — granted to the dev principal only.
+_ALL_SCOPES = frozenset({"fs:read", "fs:search", "fs:write:scratch", "ingest", "admin"})
+
+
+@dataclass(frozen=True)
+class TenantContext:
+    """The authority resolved from a request: who, in which tenant, with what."""
+
+    tenant_id: str
+    principal_id: str
+    scopes: frozenset[str] = field(default_factory=frozenset)
+    # None = all namespaces in the tenant are granted (dev convenience).
+    namespaces: frozenset[str] | None = None
+
+    def require_scope(self, scope: str) -> None:
+        if scope not in self.scopes:
+            raise InsufficientScopeError(f"missing required scope: {scope}")
+
+    def allows_namespace(self, namespace: str) -> bool:
+        return self.namespaces is None or namespace in self.namespaces
+
+
+_dev_warned = False
+
+
+def resolve_dev_context(settings: Settings) -> TenantContext:
+    """The static dev principal. Loud, intentional, never production."""
+    global _dev_warned
+    if not _dev_warned:
+        logger.warning(
+            "AFS_AUTH_MODE=dev — serving with a STATIC dev principal and no token "
+            "verification. Never run this in production."
+        )
+        _dev_warned = True
+    return TenantContext(
+        tenant_id=settings.dev_tenant_id,
+        principal_id=settings.dev_principal_id,
+        scopes=_ALL_SCOPES,
+        namespaces=None,
+    )
+
+
+def resolve_context(settings: Settings) -> TenantContext:
+    if settings.auth_mode == "dev":
+        return resolve_dev_context(settings)
+    # oidc and anything else: not implemented yet → fail closed.
+    raise UnauthenticatedError(
+        f"auth_mode {settings.auth_mode!r} is not available yet; only 'dev' is implemented"
+    )

afs_server-0.1.0/src/afs_server/dependencies.py

@@ -0,0 +1,51 @@
+"""Shared FastAPI dependencies (typed aliases keep the routers thin)."""
+
+from __future__ import annotations
+
+from functools import lru_cache
+from typing import TYPE_CHECKING, Annotated
+
+from fastapi import Depends, Request
+
+from afs_server.auth import TenantContext, resolve_context
+from afs_server.services import FsService, IngestService
+from afs_server.settings import Settings, load_settings
+
+if TYPE_CHECKING:
+    from afs_core.contracts import CatalogStore, ObjectStore
+
+
+@lru_cache
+def get_settings() -> Settings:
+    return load_settings()
+
+
+def get_catalog(request: Request) -> CatalogStore:
+    return request.app.state.catalog
+
+
+def get_objects(request: Request) -> ObjectStore:
+    return request.app.state.objects
+
+
+def get_fs_service(request: Request) -> FsService:
+    return FsService(request.app.state.catalog, request.app.state.objects)
+
+
+def get_ingest_service(request: Request) -> IngestService:
+    return IngestService(
+        request.app.state.catalog,
+        request.app.state.objects,
+        request.app.state.extraction_pipeline,
+    )
+
+
+def get_principal(settings: Annotated[Settings, Depends(get_settings)]) -> TenantContext:
+    return resolve_context(settings)
+
+
+SettingsDep = Annotated[Settings, Depends(get_settings)]
+CatalogDep = Annotated["CatalogStore", Depends(get_catalog)]
+FsDep = Annotated[FsService, Depends(get_fs_service)]
+IngestDep = Annotated[IngestService, Depends(get_ingest_service)]
+PrincipalDep = Annotated[TenantContext, Depends(get_principal)]

afs_server-0.1.0/src/afs_server/extraction/__init__.py

@@ -0,0 +1,48 @@
+"""Extraction — the pluggable parser layer.
+
+A `Normalizer` (text_native builtin, or a third-party plugin) is selected by name
+into a ladder, exactly like the store registry. Add your own parser: implement
+`afs_core.contracts.Normalizer`, certify it with
+`afs_core.testing.NormalizerConformance`, register it under the `afs.normalizers`
+entry-point group, and name it in the ladder. See `docs/swap-guides/` (extraction).
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import entry_points
+
+from afs_core.contracts import Normalizer
+from afs_server.extraction.pipeline import ExtractionOutcome, ExtractionPipeline
+from afs_server.extraction.text_native import TextNativeNormalizer
+
+_NORMALIZER_ENTRY_GROUP = "afs.normalizers"
+
+# Builtin normalizers: name -> factory.
+_BUILTIN_NORMALIZERS = {
+    "text_native": TextNativeNormalizer,
+}
+
+# Default ladder (config, not code — extended as rungs like docling land).
+DEFAULT_LADDER = ["text_native"]
+
+
+def _build_normalizer(name: str) -> Normalizer:
+    builtin = _BUILTIN_NORMALIZERS.get(name)
+    if builtin is not None:
+        return builtin()
+    for ep in entry_points(group=_NORMALIZER_ENTRY_GROUP):
+        if ep.name == name:
+            return ep.load()()
+    available = sorted(_BUILTIN_NORMALIZERS) + [
+        ep.name for ep in entry_points(group=_NORMALIZER_ENTRY_GROUP)
+    ]
+    raise ValueError(f"unknown normalizer {name!r}; available: {', '.join(available) or 'none'}")
+
+
+def build_pipeline(ladder: list[str] | None = None) -> ExtractionPipeline:
+    """Build the extraction pipeline from a ladder of normalizer names."""
+    names = ladder or DEFAULT_LADDER
+    return ExtractionPipeline([_build_normalizer(n) for n in names])
+
+
+__all__ = ["ExtractionOutcome", "ExtractionPipeline", "build_pipeline"]

afs_server-0.1.0/src/afs_server/extraction/pipeline.py

@@ -0,0 +1,50 @@
+"""The extraction pipeline — orders normalizers into a ladder, gates on quality,
+and degrades to catalog_only (plan §5.4, §9.2).
+
+This is the boundary the maintainer's feedback identified: parsers (`Normalizer`s)
+produce a `NormalizedDocument`; the pipeline decides which rung wins and whether
+the result is good enough — neither knows about S3 keys or catalog rows.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from afs_core.contracts import NormalizationError
+
+if TYPE_CHECKING:
+    from afs_core.contracts import Normalizer
+    from afs_core.models import NormalizedDocument, SourceDocument
+
+logger = logging.getLogger("afs_server.extraction")
+
+
+@dataclass(frozen=True)
+class ExtractionOutcome:
+    document: NormalizedDocument
+    extractor: str  # which rung produced it (recorded on the catalog row)
+
+
+class ExtractionPipeline:
+    """Walks the ladder in order; the first rung that accepts the document and
+    produces an above-quality-gate result wins. Returns ``None`` ⇒ catalog_only."""
+
+    def __init__(self, ladder: list[Normalizer], *, min_chars_per_page: int = 1) -> None:
+        self._ladder = ladder
+        self._min_chars = min_chars_per_page
+
+    async def run(self, doc: SourceDocument) -> ExtractionOutcome | None:
+        for nz in self._ladder:
+            if not nz.accepts(doc):
+                continue
+            try:
+                result = await nz.normalize(doc)
+            except NormalizationError as err:
+                logger.info("normalizer %s declined %s: %s", nz.name, doc.filename, err.reason)
+                continue
+            if result.pages and result.quality.min_chars_per_page >= self._min_chars:
+                return ExtractionOutcome(document=result, extractor=nz.name)
+            # below the quality gate — fall through to the next (escalation) rung.
+        return None

afs_server-0.1.0/src/afs_server/extraction/text_native.py

@@ -0,0 +1,41 @@
+"""The text_native rung — the first (and cheapest) Normalizer.
+
+Markdown/text/csv/json/html/… are already text, so "extraction" is just reading
+the bytes as one page. The richer rungs (docling for PDFs/Office, llamaparse on
+quality failure) are additional `Normalizer`s registered the same way.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from afs_core.contracts import NormalizationError
+from afs_core.models import NormalizedDocument, PageText, QualityReport
+
+if TYPE_CHECKING:
+    from afs_core.models import SourceDocument
+
+_TEXT_CONTENT_TYPES = {"application/json", "application/xml", "application/x-ndjson"}
+_TEXT_EXTENSIONS = {
+    ".md", ".markdown", ".txt", ".text", ".csv", ".tsv",
+    ".json", ".xml", ".html", ".htm", ".yaml", ".yml", ".log",
+}  # fmt: skip
+
+
+class TextNativeNormalizer:
+    name = "text_native"
+
+    def accepts(self, doc: SourceDocument) -> bool:
+        ct = doc.content_type or ""
+        if ct.startswith("text/") or ct in _TEXT_CONTENT_TYPES:
+            return True
+        return doc.local_path.suffix.lower() in _TEXT_EXTENSIONS
+
+    async def normalize(self, doc: SourceDocument) -> NormalizedDocument:
+        text = doc.local_path.read_bytes().decode("utf-8", errors="replace")
+        if not text.strip():
+            raise NormalizationError("empty_document")
+        return NormalizedDocument(
+            pages=[PageText(number=1, markdown=text, source_locator="text:1")],
+            quality=QualityReport(page_count=1, char_count=len(text), min_chars_per_page=len(text)),
+        )

afs_server-0.1.0/src/afs_server/mcp/__init__.py

@@ -0,0 +1,5 @@
+"""MCP surface — FastMCP tools over the shared service layer (no HTTP self-calls)."""
+
+from afs_server.mcp.server import build_mcp
+
+__all__ = ["build_mcp"]

afs_server-0.1.0/src/afs_server/mcp/server.py

@@ -0,0 +1,86 @@
+"""The MCP tool surface (FastMCP), backed by the same ``FsService`` the REST
+routes use — shared in-process, no HTTP self-calls (plan §7).
+
+This slice exposes the read-path tools (`whoami`, `fs_list`, `fs_stat`,
+`fs_read`) under the dev principal. The full middleware chain (per-connection
+JWKS auth, claims-filtered `tools/list`, budgets, audit) and the remaining tools
+(`fs_glob`/`fs_grep`/`fs_search`/`scratch_*`) land with their services.
+
+Tools are flat `snake_case`; the docstring **is** the tool description (it states
+the find→read flow and the bounds), per the plan.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from fastmcp import FastMCP
+from fastmcp.exceptions import ToolError
+
+from afs_core.errors import AfsError
+from afs_server.auth import resolve_context
+
+if TYPE_CHECKING:
+    from collections.abc import Awaitable
+
+    from pydantic import BaseModel
+
+    from afs_server.services import FsService
+    from afs_server.settings import Settings
+
+
+async def _result(coro: Awaitable[BaseModel]) -> dict[str, Any]:
+    """Await a service call; surface expected AfsErrors as MCP ToolErrors."""
+    try:
+        model = await coro
+    except AfsError as err:
+        raise ToolError(err.message) from err
+    return model.model_dump(mode="json")
+
+
+def build_mcp(fs: FsService, settings: Settings) -> FastMCP:
+    mcp: FastMCP = FastMCP("agentic-fs")
+
+    @mcp.tool
+    async def whoami() -> dict[str, Any]:
+        """Return the calling principal: tenant, scopes, and granted namespaces."""
+        ctx = resolve_context(settings)
+        return {
+            "tenant_id": ctx.tenant_id,
+            "principal_id": ctx.principal_id,
+            "scopes": sorted(ctx.scopes),
+            "namespaces": sorted(ctx.namespaces) if ctx.namespaces is not None else None,
+        }
+
+    @mcp.tool
+    async def fs_list(namespace: str, prefix: str = "", limit: int = 100) -> dict[str, Any]:
+        """List catalog entries in a namespace under an optional path prefix.
+
+        Start here to discover documents, then fs_read to fetch their text.
+        Returns up to `limit` entries and a `next_cursor` to page further.
+        """
+        return await _result(
+            fs.list_entries(resolve_context(settings), namespace, prefix=prefix, limit=limit)
+        )
+
+    @mcp.tool
+    async def fs_stat(namespace: str, path: str) -> dict[str, Any]:
+        """Return one document's catalog record (size, title, extraction status…)."""
+        return await _result(fs.stat(resolve_context(settings), namespace, path))
+
+    @mcp.tool
+    async def fs_read(
+        namespace: str, path: str, start_page: int = 1, end_page: int | None = None
+    ) -> dict[str, Any]:
+        """Read a bounded page range (<= 20 pages) of a document's extracted text.
+
+        A `catalog_only` document exists and is citeable but isn't readable yet —
+        you'll get a tool error saying so; you can still reference it by path.
+        """
+        return await _result(
+            fs.read(
+                resolve_context(settings), namespace, path, start_page=start_page, end_page=end_page
+            )
+        )
+
+    return mcp

afs_server-0.1.0/src/afs_server/routers/__init__.py

@@ -0,0 +1 @@
+"""HTTP routers."""