Metadata-Version: 2.4
Name: documint-mcp
Version: 0.3.2
Summary: Documint V1 backend for repo-native documentation operations
Project-URL: Homepage, https://documint.xyz
Project-URL: Repository, https://github.com/skeehn/documint
Project-URL: Issues, https://github.com/skeehn/documint/issues
Author-email: Documint Team <team@documint.xyz>
License-Expression: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.11
Requires-Dist: aiofiles>=23.2.0
Requires-Dist: alembic>=1.16.0
Requires-Dist: anthropic>=0.40.0
Requires-Dist: arq>=0.26.3
Requires-Dist: cryptography>=45.0.0
Requires-Dist: fastapi>=0.104.0
Requires-Dist: httpx>=0.25.0
Requires-Dist: instructor>=1.3.0
Requires-Dist: lancedb>=0.6.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: passlib[bcrypt]>=1.7.4
Requires-Dist: prometheus-client>=0.19.0
Requires-Dist: psycopg2-binary>=2.9.10
Requires-Dist: pyarrow>=14.0.0
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: pydantic>=2.4.0
Requires-Dist: pyjwt>=2.10.1
Requires-Dist: python-jose[cryptography]>=3.3.0
Requires-Dist: python-multipart>=0.0.6
Requires-Dist: pyyaml>=6.0.2
Requires-Dist: redis>=5.0.0
Requires-Dist: slowapi>=0.1.9
Requires-Dist: sqlalchemy>=2.0.36
Requires-Dist: structlog>=23.2.0
Requires-Dist: tomli-w>=1.0.0
Requires-Dist: uvicorn[standard]>=0.24.0
Provides-Extra: dev
Requires-Dist: black>=23.9.0; extra == 'dev'
Requires-Dist: mypy>=1.6.0; extra == 'dev'
Requires-Dist: pre-commit>=3.5.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
Requires-Dist: pytest>=7.4.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Provides-Extra: mcp
Requires-Dist: mcp>=1.0.0; extra == 'mcp'
Provides-Extra: slack
Requires-Dist: slack-sdk>=3.0; extra == 'slack'
Provides-Extra: tree-sitter
Requires-Dist: tree-sitter-javascript>=0.23.0; extra == 'tree-sitter'
Requires-Dist: tree-sitter-python>=0.23.0; extra == 'tree-sitter'
Requires-Dist: tree-sitter-typescript>=0.23.0; extra == 'tree-sitter'
Requires-Dist: tree-sitter>=0.23.0; extra == 'tree-sitter'
Provides-Extra: voyage
Requires-Dist: voyageai>=0.3.0; extra == 'voyage'
Provides-Extra: watch
Requires-Dist: watchdog>=3.0; extra == 'watch'
Description-Content-Type: text/markdown

# Documint

Documint is a repo-native documentation operations product for teams that ship APIs, SDKs, and MCP servers.

The first customer is this repository itself. V1 is deliberately narrow:

- Git is the source of truth.
- documentation changes happen through commits and PRs,
- the public site lives at `documint.xyz`,
- the backend detects doc drift and exposes a published-docs MCP surface,
- the product is not considered ready until it can keep its own docs current.

## Product surfaces

- `/` marketing and positioning
- `/docs` published repo-backed documentation
- `/app` the authenticated operator console for onboarding, traces, findings, patches, PRs, publishes, and tokens
- `/p/:workspace/:project/docs/...` hosted public docs generated from persisted publish deployments

## Stack

- `apps/web`: Next.js site and dashboard
- `src/documint_mcp`: Python backend, persistent control plane, drift engine, GitHub App integration, and MCP-style API
- `content/docs`: published docs content for the self-dogfood project
- `alembic`: schema migrations for the control-plane database

## Local development

### 1. Install dependencies

```bash
npm install
cd apps/web && npm install && cd ../..
python -m pip install -e ".[dev]"
```

### 2. Create or migrate the database

```bash
documint db upgrade
```

For local dogfooding, schema creation and self-bootstrap can also be driven by env flags:

- `DOCUMINT_AUTO_CREATE_SCHEMA=true`
- `DOCUMINT_AUTO_BOOTSTRAP_DEFAULTS=true`

### 3. Run the backend

```bash
npm run dev:api
```

### 4. Run the site

```bash
npm run dev:web
```

The site expects the backend at `http://127.0.0.1:8000` by default. Override with `DOCUMINT_API_URL` if needed.

### 5. Bootstrap the self project explicitly when auto-bootstrap is off

```bash
documint workspaces bootstrap-self
```

### 6. Run the queue worker when `DOCUMINT_JOB_EXECUTION_MODE=queue`

```bash
documint worker
```

### 7. Run the full dogfood smoke loop

```bash
npm run dogfood
```

This boots the backend and web app, verifies the public pages, runs drift and publish jobs, calls the MCP surface, and posts a signed GitHub webhook delivery against the local API.

## Core API routes

- `GET /health`
- `GET /runtime`
- `GET /me`
- `GET /workspaces`
- `POST /workspaces`
- `GET /snapshot`
- `GET /projects`
- `POST /projects`
- `GET /projects/{project_id}`
- `POST /projects/{project_id}/rescan`
- `GET /projects/{project_id}/findings`
- `POST /projects/{project_id}/findings/{finding_id}/patch`
- `GET /projects/{project_id}/patches`
- `GET /projects/{project_id}/patches/{patch_id}`
- `POST /projects/{project_id}/patches/{patch_id}/pr`
- `GET /projects/{project_id}/publishes`
- `GET /projects/{project_id}/activity`
- `GET /sources`
- `GET /workspaces/{workspace_id}/tokens`
- `POST /workspaces/{workspace_id}/tokens`
- `GET /integrations/github/app`
- `GET /integrations/github/installations`
- `GET /integrations/github/installations/{installation_id}/repositories`
- `POST /integrations/github/installations/{installation_id}/sync`
- `POST /integrations/github/webhooks`
- `POST /jobs/drift`
- `POST /jobs/publish`
- `POST /auth/cli/exchange`
- `POST /internal/revalidate`
- `GET /artifacts/{artifact_id}/trace`
- `GET /public/projects/{workspace_slug}/{project_slug}/docs/{path}`
- `GET /mcp`
- `POST /mcp`

## MCP tools

- `list_projects`
- `analyze_repository`
- `detect_doc_drift`
- `generate_doc_patch`
- `review_doc_patch`
- `publish_preview`
- `explain_doc_trace`
- `get_project_activity`

## Release bar

Documint does not onboard external customers until it can do the following on this repo:

1. produce a truthful project snapshot,
2. detect stale documentation from source changes,
3. generate a reviewable patch preview,
4. publish a docs preview,
5. expose those docs through the MCP surface.

## Deployment shape

- Deploy `apps/web` to Vercel with the project root directory set to `apps/web`.
- Deploy the Python backend to Railway from the repository root using `railway.json` and the root [Dockerfile](/Users/kstephenkeehn/documint/Dockerfile).
- Point `DOCUMINT_API_URL` at the public backend origin for the dashboard.
- Set `API_BASE_URL`, `GITHUB_WEBHOOK_SECRET`, `GITHUB_APP_PRIVATE_KEY`, and `DOCUMINT_SELF_BOOTSTRAP_INSTALLATION_ID` before configuring the GitHub App webhook.
- Set Clerk env vars in both web and backend runtimes:
  - `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY`
  - `CLERK_SECRET_KEY`
  - `CLERK_JWKS_URL`
  - `CLERK_ISSUER`
  - `CLERK_AUDIENCE`
- Set `DOCUMINT_FRONTEND_REVALIDATE_URL`, `DOCUMINT_FRONTEND_REVALIDATE_SECRET`, and `DOCUMINT_INTERNAL_REVALIDATE_SECRET` so publish jobs can invalidate hosted docs pages.
- Set `PUBLIC_BASE_URL=https://documint.xyz`, `APP_BASE_URL=https://documint.xyz/app`, and `DOCUMINT_DEPLOY_COMMIT` if your runtime does not expose git metadata.
- For a local containerized stack, run `docker compose up --build`.

## Production proof

- `/runtime` must report the deployed provider, environment, and commit source.
- `/app` must show `live api`, not `fallback data`.
- `npm run dogfood` now verifies the live dashboard path as part of the self-test.

## GitHub App loop

Documint V1 treats GitHub as the first event source for self-dogfooding:

1. create a GitHub App with `push`, `pull_request`, `release`, `installation`, and `installation_repositories` events,
2. set the webhook URL to `https://<api-origin>/integrations/github/webhooks`,
3. install the app on `skeehn/documint`,
4. sync the installation repo catalog in `/app/onboarding`,
5. let webhook deliveries trigger repo-backed drift checks,
6. review the findings and proposed patch before opening or merging a docs PR.

## Auth and operator flow

- Production `/app` routes are protected with Clerk when Clerk is configured.
- The backend accepts three credential types:
  - service bearer token for internal bootstrap/admin flows
  - hashed workspace API tokens for CLI and MCP
  - Clerk JWTs for the operator app
- Production operator pages no longer render fake project state when the backend is unavailable. They render a degraded unavailable state instead.

## Local full-stack options

- `npm run dogfood` is the fastest end-to-end local smoke test.
- `docker compose up --build` runs the repo-native stack with `web`, `api`, and `redis`.
- `docker compose -f docker/docker-compose.dev.yml up --build` provides the same stack from the legacy `docker/` entrypoint, now aligned with V1.
