adapt-server 0.2.2__tar.gz → 0.2.4__tar.gz

{adapt_server-0.2.2 → adapt_server-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: adapt-server
-Version: 0.2.2
+Version: 0.2.4
 Summary: Adaptive file-backed FastAPI server that turns datasets into CRUD APIs and UIs.
 Author-email: notesofcliff <notesofcliff@gmail.com>
 License-Expression: MIT
@@ -21,7 +21,7 @@ Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: fastapi
+Requires-Dist: fastapi>=0.115
 Requires-Dist: uvicorn
 Requires-Dist: sqlmodel
 Requires-Dist: pendulum
@@ -36,6 +36,7 @@ Requires-Dist: pillow
 Requires-Dist: python-json-logger
 Requires-Dist: pandas
 Requires-Dist: fastparquet
+Requires-Dist: mcp<2,>=1.28
 Provides-Extra: dev
 Requires-Dist: pytest; extra == "dev"
 Requires-Dist: httpx; extra == "dev"
@@ -51,6 +52,8 @@ Adapt is a FastAPI server that turns files in a directory into APIs and UIs.
 - Markdown/HTML become browsable pages
 - Media files become streaming endpoints and player/gallery UIs
 - Python files can register custom routers
+- Everything is searchable in one place via full-text `/search`
+- Everything is reachable by agentic tools via an MCP server at `/mcp`
 
 ## Quick Start
 
@@ -81,6 +84,8 @@ Useful URLs:
 - `/api/<resource>` resource API
 - `/ui/<resource>` resource UI
 - `/schema/<resource>` resource schema
+- `/search` full-text search across every resource you can read
+- `/mcp` MCP server for agentic tools (see [MCP Interface](#mcp-interface) below)
 
 ## What Adapt Generates
 
@@ -135,6 +140,73 @@ This reflects the current implementation in the codebase.
 - Caching with invalidation on mutations
 - Built-in admin UI for users/groups/permissions/locks/cache/api keys/audit logs
 - Plugin architecture with companion overrides in `.adapt/`
+- Permission-filtered full-text search across every resource type
+- MCP server for agentic tool access, mounted alongside the REST API
+
+## Full-Text Search
+
+`GET /search?q=<query>` searches datasets, Markdown, HTML, and media metadata
+in one ranked list, filtered to what the caller may read — a query term that
+matches a resource you can't see never shows up, and never leaks via the
+result count either.
+
+```bash
+curl -H "X-API-Key: <key>" "http://localhost:8000/search?q=parental+leave"
+```
+
+The index refreshes incrementally on startup (`search_on_startup`, default
+`true`) and can be rebuilt on demand with `adapt reindex <root>`. See the
+[API Reference](docs/manual/api_reference.md#search-endpoint) for query
+parameters and result shape.
+
+## MCP Interface
+
+Adapt mounts a [Model Context Protocol](https://modelcontextprotocol.io)
+server at `/mcp`, on the same host/port as everything else, exposing five
+tools that wrap the same permission checks and plugin methods as the REST
+API — `list_resources`, `get_schema`, `read_resource`, `write_resource`, and
+`search`. There's no separate process, no separate API surface, and no
+extra permission model to maintain.
+
+Minimal walkthrough — create an account for the agent, grant it read access,
+mint an API key, and connect a client:
+
+```bash
+adapt addsuperuser /path/to/docroot --username admin
+adapt serve /path/to/docroot &
+
+adapt admin create-permissions /path/to/docroot __all__
+adapt admin create-user /path/to/docroot --username agent --password <strong-password>
+adapt admin add-to-group /path/to/docroot --username agent --group <resource>_readonly
+```
+
+Log in as `agent` and self-issue an API key from `/profile` (any
+authenticated user can create their own key — no superuser needed), then
+point a client at `/mcp` with that key:
+
+```bash
+# Claude Code CLI
+claude mcp add --transport http adapt http://localhost:8000/mcp \
+  --header "X-API-Key: <key>"
+```
+
+```json
+// Generic MCP client config (Claude Desktop and similar)
+{
+  "mcpServers": {
+    "adapt": {
+      "url": "http://localhost:8000/mcp",
+      "headers": { "X-API-Key": "<key>" }
+    }
+  }
+}
+```
+
+MCP requires an API key on every call — there's no session-cookie or
+anonymous path, since MCP has no concept of a browser session. Set
+`mcp_enabled: false` in `.adapt/conf.json` (or `ADAPT_MCP_ENABLED=false`) to
+remove `/mcp` entirely. Full walkthrough, troubleshooting, and the tool
+reference table: [docs/manual/mcp_guide.md](docs/manual/mcp_guide.md).
 
 ## Dataset Mutation Envelope
 
@@ -156,6 +228,7 @@ adapt serve <root> [--host ... --port ... --tls-cert ... --tls-key ... --reload
 adapt check <root>
 adapt addsuperuser <root> --username <name>
 adapt list-endpoints <root>
+adapt reindex <root> [--force]
 adapt admin list-resources <root>
 adapt admin create-permissions <root> __all__
 ```
@@ -169,6 +242,7 @@ Detailed docs live under `docs/manual/`.
 - Quick start: [docs/manual/quick_start.md](docs/manual/quick_start.md)
 - Configuration: [docs/manual/configuration.md](docs/manual/configuration.md)
 - API reference: [docs/manual/api_reference.md](docs/manual/api_reference.md)
+- MCP guide: [docs/manual/mcp_guide.md](docs/manual/mcp_guide.md)
 - Plugin development: [docs/manual/plugin_development.md](docs/manual/plugin_development.md)
 
 ## License

{adapt_server-0.2.2 → adapt_server-0.2.4}/README.md

@@ -6,6 +6,8 @@ Adapt is a FastAPI server that turns files in a directory into APIs and UIs.
 - Markdown/HTML become browsable pages
 - Media files become streaming endpoints and player/gallery UIs
 - Python files can register custom routers
+- Everything is searchable in one place via full-text `/search`
+- Everything is reachable by agentic tools via an MCP server at `/mcp`
 
 ## Quick Start
 
@@ -36,6 +38,8 @@ Useful URLs:
 - `/api/<resource>` resource API
 - `/ui/<resource>` resource UI
 - `/schema/<resource>` resource schema
+- `/search` full-text search across every resource you can read
+- `/mcp` MCP server for agentic tools (see [MCP Interface](#mcp-interface) below)
 
 ## What Adapt Generates
 
@@ -90,6 +94,73 @@ This reflects the current implementation in the codebase.
 - Caching with invalidation on mutations
 - Built-in admin UI for users/groups/permissions/locks/cache/api keys/audit logs
 - Plugin architecture with companion overrides in `.adapt/`
+- Permission-filtered full-text search across every resource type
+- MCP server for agentic tool access, mounted alongside the REST API
+
+## Full-Text Search
+
+`GET /search?q=<query>` searches datasets, Markdown, HTML, and media metadata
+in one ranked list, filtered to what the caller may read — a query term that
+matches a resource you can't see never shows up, and never leaks via the
+result count either.
+
+```bash
+curl -H "X-API-Key: <key>" "http://localhost:8000/search?q=parental+leave"
+```
+
+The index refreshes incrementally on startup (`search_on_startup`, default
+`true`) and can be rebuilt on demand with `adapt reindex <root>`. See the
+[API Reference](docs/manual/api_reference.md#search-endpoint) for query
+parameters and result shape.
+
+## MCP Interface
+
+Adapt mounts a [Model Context Protocol](https://modelcontextprotocol.io)
+server at `/mcp`, on the same host/port as everything else, exposing five
+tools that wrap the same permission checks and plugin methods as the REST
+API — `list_resources`, `get_schema`, `read_resource`, `write_resource`, and
+`search`. There's no separate process, no separate API surface, and no
+extra permission model to maintain.
+
+Minimal walkthrough — create an account for the agent, grant it read access,
+mint an API key, and connect a client:
+
+```bash
+adapt addsuperuser /path/to/docroot --username admin
+adapt serve /path/to/docroot &
+
+adapt admin create-permissions /path/to/docroot __all__
+adapt admin create-user /path/to/docroot --username agent --password <strong-password>
+adapt admin add-to-group /path/to/docroot --username agent --group <resource>_readonly
+```
+
+Log in as `agent` and self-issue an API key from `/profile` (any
+authenticated user can create their own key — no superuser needed), then
+point a client at `/mcp` with that key:
+
+```bash
+# Claude Code CLI
+claude mcp add --transport http adapt http://localhost:8000/mcp \
+  --header "X-API-Key: <key>"
+```
+
+```json
+// Generic MCP client config (Claude Desktop and similar)
+{
+  "mcpServers": {
+    "adapt": {
+      "url": "http://localhost:8000/mcp",
+      "headers": { "X-API-Key": "<key>" }
+    }
+  }
+}
+```
+
+MCP requires an API key on every call — there's no session-cookie or
+anonymous path, since MCP has no concept of a browser session. Set
+`mcp_enabled: false` in `.adapt/conf.json` (or `ADAPT_MCP_ENABLED=false`) to
+remove `/mcp` entirely. Full walkthrough, troubleshooting, and the tool
+reference table: [docs/manual/mcp_guide.md](docs/manual/mcp_guide.md).
 
 ## Dataset Mutation Envelope
 
@@ -111,6 +182,7 @@ adapt serve <root> [--host ... --port ... --tls-cert ... --tls-key ... --reload
 adapt check <root>
 adapt addsuperuser <root> --username <name>
 adapt list-endpoints <root>
+adapt reindex <root> [--force]
 adapt admin list-resources <root>
 adapt admin create-permissions <root> __all__
 ```
@@ -124,6 +196,7 @@ Detailed docs live under `docs/manual/`.
 - Quick start: [docs/manual/quick_start.md](docs/manual/quick_start.md)
 - Configuration: [docs/manual/configuration.md](docs/manual/configuration.md)
 - API reference: [docs/manual/api_reference.md](docs/manual/api_reference.md)
+- MCP guide: [docs/manual/mcp_guide.md](docs/manual/mcp_guide.md)
 - Plugin development: [docs/manual/plugin_development.md](docs/manual/plugin_development.md)
 
 ## License

{adapt_server-0.2.2 → adapt_server-0.2.4}/adapt/__init__.py

@@ -1,3 +1,3 @@
 """Adapt package namespace."""
 
-__version__ = "0.2.2"
+__version__ = "0.2.4"

{adapt_server-0.2.2 → adapt_server-0.2.4}/adapt/admin/api_keys.py

@@ -1,13 +1,14 @@
+import json
+import logging
+from typing import List
+
 from fastapi import Depends, HTTPException, Request, Query
 from sqlalchemy import asc, desc
 from sqlmodel import Session, select
-from typing import List
-from datetime import datetime, timedelta, timezone
-import logging
 
 from ..auth import require_superuser
 from ..storage import User, APIKey, get_db_session
-from ..api_keys import generate_api_key
+from ..api_keys import create_api_key_record, revoke_api_key_record
 from ..audit import log_action
 from . import router
 from .models import APIKeyCreate
@@ -27,8 +28,6 @@ def list_api_keys(
     user = Depends(require_superuser)
 ):
     """List all API keys in the system with optional query parameters."""
-    import json
-
     stmt = select(APIKey)
 
     if user_id is not None:
@@ -73,28 +72,15 @@ def create_api_key(key_data: APIKeyCreate, request: Request, db: Session = Depen
     if not target_user:
         logger.warning("Attempted to create API key for non-existent user %d", key_data.user_id)
         raise HTTPException(status_code=404, detail="User not found")
-        
-    raw_key, key_hash = generate_api_key()
-    
-    expires_at = None
-    if key_data.expires_in_days is not None:
-        if key_data.expires_in_days > 365:
-            raise HTTPException(status_code=400, detail="Expiration cannot exceed 1 year (365 days)")
-        expires_at = datetime.now(tz=timezone.utc) + timedelta(days=key_data.expires_in_days)
-        
-    api_key = APIKey(
-        user_id=key_data.user_id,
-        key_hash=key_hash,
-        description=key_data.description,
-        expires_at=expires_at
-    )
-    db.add(api_key)
-    db.commit()
-    db.refresh(api_key)
-    
+
+    try:
+        raw_key, api_key = create_api_key_record(db, key_data.user_id, key_data.description, key_data.expires_in_days)
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
     log_action(request, "create_api_key", "apikey", f"Created API key for user {target_user.username}", user.id)
     logger.info("Created API key %d for user %s", api_key.id, target_user.username)
-    
+
     # Return the raw key only once!
     return {
         "id": api_key.id,
@@ -108,16 +94,12 @@ def create_api_key(key_data: APIKeyCreate, request: Request, db: Session = Depen
 @router.delete("/api-keys/{key_id}")
 def revoke_api_key(key_id: int, request: Request, db: Session = Depends(get_db_session), user = Depends(require_superuser)):
     """Revoke an API key by ID."""
-    api_key = db.get(APIKey, key_id)
+    api_key = revoke_api_key_record(db, key_id)
     if not api_key:
         logger.warning("Attempted to revoke non-existent API key %d", key_id)
         raise HTTPException(status_code=404, detail="API Key not found")
-        
-    api_key.is_active = False
-    db.add(api_key)
-    db.commit()
-    
+
     log_action(request, "revoke_api_key", "apikey", f"Revoked API key {key_id}", user.id)
     logger.info("Revoked API key %d", key_id)
-    
+
     return {"success": True}

{adapt_server-0.2.2 → adapt_server-0.2.4}/adapt/admin/locks.py

@@ -1,11 +1,14 @@
+import json
+import logging
+from typing import List
+
 from fastapi import Depends, HTTPException, Request, Query
 from sqlmodel import Session, select
-from typing import List
-import logging
 
 from ..auth import require_superuser
 from ..storage import LockRecord, get_db_session
 from ..locks import LockManager
+from ..utils.query import apply_filter, apply_sort, apply_pagination
 from ..audit import log_action
 from . import router
 
@@ -22,9 +25,6 @@ def list_locks(
     user = Depends(require_superuser)
 ):
     """List all active locks with optional query parameters."""
-    from ..utils.query import apply_filter, apply_sort, apply_pagination
-    import json
-    
     locks = db.exec(select(LockRecord)).all()
     
     # Convert to dicts for filtering/sorting

{adapt_server-0.2.2 → adapt_server-0.2.4}/adapt/admin/ui.py

@@ -30,4 +30,4 @@ def admin_ui(request: Request):
 
     # Serve the admin template
     logger.debug("Rendering admin UI for superuser %s", user.username)
-    return request.app.state.templates.TemplateResponse("admin/index.html", context)
+    return request.app.state.templates.TemplateResponse(request, "admin/index.html", context)

{adapt_server-0.2.2 → adapt_server-0.2.4}/adapt/admin/users.py

@@ -1,10 +1,13 @@
+import json
+import logging
+from typing import List
+
 from fastapi import Depends, HTTPException, Request, Query
 from sqlmodel import Session, select
-from typing import List
-import logging
 
 from ..auth import require_superuser, hash_password
 from ..storage import User, get_db_session
+from ..utils.query import apply_filter, apply_sort, apply_pagination
 from ..audit import log_action
 from . import router
 from .models import UserCreate, UserPublic
@@ -22,9 +25,6 @@ def list_users(
     user: User = Depends(require_superuser)
 ):
     """List all users with optional query parameters."""
-    from ..utils.query import apply_filter, apply_sort, apply_pagination
-    import json
-    
     query = select(User)
     users = db.exec(query).all()
     
@@ -75,7 +75,6 @@ def create_user(user_data: UserCreate, request: Request, db: Session = Depends(g
     """Create a new user."""
     # Check if server is in read-only mode
     if request.app.state.config.readonly:
-        from fastapi import HTTPException
         raise HTTPException(status_code=405, detail="Server is in read-only mode")
     
     existing = db.exec(select(User).where(User.username == user_data.username)).first()
@@ -109,7 +108,6 @@ def delete_user(user_id: int, request: Request, db: Session = Depends(get_db_ses
     """Delete a user by ID."""
     # Check if server is in read-only mode
     if request.app.state.config.readonly:
-        from fastapi import HTTPException
         raise HTTPException(status_code=405, detail="Server is in read-only mode")
     
     target = db.get(User, user_id)

{adapt_server-0.2.2 → adapt_server-0.2.4}/adapt/api_keys.py

@@ -1,9 +1,10 @@
+"""adapt.api_keys — API key generation, verification, and lifecycle helpers."""
 from __future__ import annotations
 
 import logging
 import secrets
 import hashlib
-from datetime import datetime, timezone
+from datetime import datetime, timedelta, timezone
 from sqlmodel import Session, select
 from fastapi import Request, HTTPException, Security
 from fastapi.security import APIKeyHeader
@@ -60,6 +61,55 @@ def verify_api_key(db: Session, raw_key: str) -> User | None:
     logger.info(f"API key verified successfully for user {api_key.user_id}")
     return db.get(User, api_key.user_id)
 
+def create_api_key_record(
+    db: Session,
+    user_id: int,
+    description: str | None,
+    expires_in_days: int | None,
+) -> tuple[str, APIKey]:
+    """Create and persist an API key. Returns (raw_key, api_key).
+
+    Raises ValueError if expires_in_days exceeds 365.
+    """
+    if expires_in_days is not None and expires_in_days > 365:
+        raise ValueError("Expiration cannot exceed 1 year (365 days)")
+    expires_at = None
+    if expires_in_days is not None:
+        expires_at = datetime.now(tz=timezone.utc) + timedelta(days=expires_in_days)
+    raw_key, key_hash = generate_api_key()
+    api_key = APIKey(
+        user_id=user_id,
+        key_hash=key_hash,
+        description=description,
+        expires_at=expires_at,
+        created_at=datetime.now(tz=timezone.utc),
+        is_active=True,
+    )
+    db.add(api_key)
+    db.commit()
+    db.refresh(api_key)
+    return raw_key, api_key
+
+
+def revoke_api_key_record(
+    db: Session,
+    key_id: int,
+    *,
+    owner_id: int | None = None,
+) -> APIKey | None:
+    """Set an API key inactive. If owner_id is given, enforces ownership.
+
+    Returns the key on success, None if not found or ownership mismatch.
+    """
+    api_key = db.get(APIKey, key_id)
+    if not api_key or (owner_id is not None and api_key.user_id != owner_id):
+        return None
+    api_key.is_active = False
+    db.add(api_key)
+    db.commit()
+    return api_key
+
+
 def get_user_from_api_key(
     request: Request, 
     api_key: str = Security(API_KEY_HEADER)