Files
Dashboard_Projects_Management/README.md
T

3.5 KiB

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

.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:

.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.