Metadata-Version: 2.4
Name: adapt-server
Version: 0.2.8
Summary: Adaptive file-backed FastAPI server that turns datasets into CRUD APIs and UIs.
Author-email: notesofcliff <notesofcliff@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://www.mcindi.com/software/adapt/
Project-URL: Repository, https://github.com/McIndi/adapt
Project-URL: Issues, https://github.com/McIndi/adapt/issues
Keywords: fastapi,api,csv,excel,parquet,markdown,media
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi>=0.115
Requires-Dist: uvicorn
Requires-Dist: sqlmodel
Requires-Dist: pendulum
Requires-Dist: watchfiles
Requires-Dist: jinja2
Requires-Dist: openpyxl
Requires-Dist: markdown
Requires-Dist: python-multipart
Requires-Dist: mutagen
Requires-Dist: moviepy
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"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Dynamic: license-file

# Adapt

Adapt is a FastAPI server that turns files in a directory into APIs and UIs.

- Datasets (`.csv`, `.xlsx`, `.parquet`) become CRUD endpoints and DataTables 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

```bash
pip install adapt-server
adapt addsuperuser --username admin /path/to/docroot
adapt serve /path/to/docroot

# Generate permissions for all discovered resources
adapt admin create-permissions /path/to/docroot __all__

# Everything below here can be done in the admin UI at
# http://localhost:8000/admin/ after logging in with the superuser account.
#
# Create a regular user
adapt admin create-user --username editor --password secret /path/to/docroot

# By default, the editor user has no permissions.
# See available groups (created by `adapt admin create-permissions`) and assign user to desired group
adapt admin list-groups /path/to/docroot
adapt admin add-to-group --username editor --group <group_name> /path/to/docroot
```

Useful URLs:

- `/` landing page
- `/admin/` admin UI
- `/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

From files in your docroot, Adapt auto-discovers resources and mounts routes with extensionless URLs where possible.

Example:

```text
data/
  employees.csv
  sales.xlsx
  video.mp4
  readme.md
  stats.py
```

Rough output:

- `/api/employees`, `/ui/employees`, `/schema/employees`
- `/api/sales/<sheet>`, `/ui/sales/<sheet>`
- `/media/video.mp4`, `/ui/video.mp4`, `/ui/media`
- `/readme`
- `/api/stats/*`

## Current Security Posture

This reflects the current implementation in the codebase.

### In Place

- **Authentication:** session cookies and API keys (`X-API-Key`)
- **Authorization:** RBAC (users, groups, permissions), plus superuser bypass
- **Password security:** PBKDF2 hashing with per-user salts
- **Session security:** expiration enforcement, sliding renewal, cleanup task
- **CSRF protection:** enforced for cookie-authenticated unsafe methods (`POST/PUT/PATCH/DELETE`), including mixed session + API-key requests
- **Redirect hardening:** login `next` paths are validated as local relative paths
- **Response hardening:** CSP, `X-Frame-Options`, `X-Content-Type-Options`, `Referrer-Policy`, `Permissions-Policy`, HSTS (when TLS is enabled)
- **Host header hardening:** Trusted Host middleware
- **Data integrity:** lock-based, atomic writes for mutable dataset plugins
- **Auditability:** admin/audit logging for security-relevant actions
- **Sensitive response cleanup:** admin user APIs no longer expose `password_hash`

### Important Deployment Notes

- Use TLS in non-local environments (`--tls-cert` + `--tls-key`) so secure cookies and HSTS protections are effective.
- API-key-only clients are exempt from CSRF checks by design; cookie-auth browser flows require CSRF tokens.

## Core Features

- Adaptive discovery and route generation
- Dataset CRUD with schema exposure
- 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).
For dataset reads, `sort` is the column name and `order` must be `asc` or
`desc`.

## Dataset Mutation Envelope

For dataset endpoints, write operations use this payload structure:

```json
{
  "action": "create|update|delete",
  "data": []
}
```

Use object data for `update`/`delete` as needed (for example, with `_row_id`).

## CLI (Common Commands)

```bash
adapt serve <root> [--host ... --port ... --tls-cert ... --tls-key ... --reload --readonly --debug]
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__
```

## Documentation

Detailed docs live under `docs/manual/`.

- Manual index: [docs/manual/index.md](docs/manual/index.md)
- Security: [docs/manual/security.md](docs/manual/security.md)
- 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

MIT. See [LICENSE](LICENSE).
