41 lines
3.5 KiB
Markdown
41 lines
3.5 KiB
Markdown
# Common Ground dashboard and projects
|
|
|
|
Django dashboard with an authenticated project manager, Kanban boards, Markdown specifications, and a separate Streamable HTTP MCP server. The original Today, Health, Energy, Home, and Showcase page templates remain in place.
|
|
|
|
## Local setup
|
|
|
|
```sh
|
|
.venv/bin/python -m pip install -r requirements.txt
|
|
.venv/bin/python manage.py migrate
|
|
.venv/bin/python manage.py createsuperuser
|
|
npm install
|
|
npm run dev
|
|
```
|
|
|
|
The dashboard runs at `http://127.0.0.1:8765/`. `npm run dev` uses the existing package scripts; `npm run dev:mcp` starts the MCP process at `http://127.0.0.1:8766/mcp`. If Node.js is unavailable, use `.venv/bin/uvicorn mcp_server.server:app --host 127.0.0.1 --port 8766`. Port 8766 is separate from TasksNest's MCP listener.
|
|
|
|
`/projects/` contains active and archived projects. New projects seed editable To-do, In Progress, and Done columns. New cards use the board's selected default column and Medium priority. Cards store raw Markdown, a revision history, explicit blockers, comments, and activity. HTML output is sanitized. Git URLs are metadata; the server does not fetch or clone them.
|
|
|
|
## OAuth and MCP
|
|
|
|
The Django server hosts OAuth authorization, token, revocation, and discovery endpoints under `/o/` and `/.well-known/oauth-authorization-server`. The MCP process hosts `/mcp` and `/.well-known/oauth-protected-resource/mcp`. The server registers 51 tools; reads require `projects:read`, and writes require `projects:write`. OAuth authorization codes require PKCE. Tokens expire after one hour, can be revoked from Profile, and are stored hashed by django-oauth-toolkit.
|
|
|
|
Authenticated dynamic client registration is enabled at `/o/register/`. A signed-in user can register a client; session requests also need a CSRF token. Anonymous registration is denied. You can also create a public authorization-code client in Django admin, setting its exact HTTPS redirect URI and the needed scopes. Profile shows active grants and revocation controls.
|
|
|
|
Local accounts work by default. To enable separate OIDC sign-in to the dashboard, set `OIDC_OP_ISSUER`, `OIDC_OP_AUTHORIZATION_ENDPOINT`, `OIDC_OP_TOKEN_ENDPOINT`, `OIDC_OP_USER_ENDPOINT`, `OIDC_OP_JWKS_ENDPOINT`, `OIDC_RP_CLIENT_ID`, and `OIDC_RP_CLIENT_SECRET`. Register `/oidc/callback/` at the provider. OIDC identities are linked by verified issuer and subject; a matching email does not link an existing local account. The actual provider callback still needs an integration test with your provider configuration.
|
|
|
|
Set `MCP_PUBLIC_URL` and `OAUTH_ISSUER_URL` to the public HTTPS MCP endpoint and Django origin. Route `/mcp` and `/.well-known/oauth-protected-resource/mcp` to port 8766, and OAuth routes to the Django process. Preserve the Authorization header. The MCP process and Django must use the same database and `DJANGO_SECRET_KEY`.
|
|
|
|
## Deployment settings
|
|
|
|
Set `DJANGO_DEBUG=0`, a strong `DJANGO_SECRET_KEY`, `DJANGO_ALLOWED_HOSTS`, `MCP_PUBLIC_URL`, and `OAUTH_ISSUER_URL`. `DJANGO_CSRF_TRUSTED_ORIGINS` accepts a comma-separated origin list if needed behind a proxy. Production mode requires HTTPS URLs and enables secure cookies, SSL redirect, and HSTS. The local sign-in throttle uses Django's process-local cache; use a shared cache when running multiple workers.
|
|
|
|
Run checks and tests with:
|
|
|
|
```sh
|
|
.venv/bin/python manage.py check
|
|
.venv/bin/python manage.py test projects
|
|
```
|
|
|
|
For compiled frontend assets, run `npm run build`. Django uses Vite in development, the build manifest when present, and checked-in preview assets otherwise.
|