bvandeusenandClaude Opus 5.5
3474cdff46
MCP-8 #4972 "Connect card, docs, and end-to-end integration test". - AI access page: a "Connect a client" card with the /mcp URL (from Settings → General → Public base URL, else the request host) and recipes for Claude Code, Claude Desktop (mcp-remote) and other Streamable HTTP clients, plus the reverse-proxy note. The token-created page shows the same recipes with the new token filled in, ready to paste. - docs/core/mcp.md: connecting, the reverse-proxy requirements, the security model (token ceiling, default deny, check-mode default, secrets, audit), tools by role, response conventions, adding tools. docs/architecture.md describes the /mcp dispatch outside the blueprint pipeline; docs/reference/code-map.md gains an MCP section. - tests/integration/test_mcp.py: over HTTP, a viewer token lists no write tools and is refused one by name; an operator token reads get_overview and its maintenance-window create/end land in the audit log as "<user> via MCP" with the token id. (Revoked → 401 was already covered.) Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
161 lines
7.1 KiB
Markdown
161 lines
7.1 KiB
Markdown
# Code Map
|
|
|
|
Quick reference for where key functions, models, and entry points live in the codebase.
|
|
|
|
---
|
|
|
|
## Application Bootstrap
|
|
|
|
| What | File | Function / Class |
|
|
|---|---|---|
|
|
| App factory | `steward/app.py` | `create_app()` |
|
|
| CLI entry point | `steward/cli.py` | `main()` |
|
|
| Bootstrap config loading | `steward/config.py` | `load_bootstrap()` |
|
|
| Secret key resolution | `steward/config.py` | `_resolve_secret_key()` |
|
|
| DB engine init | `steward/database.py` | `init_db()` |
|
|
| Core migrations | `steward/core/migration_runner.py` | `run_core_migrations()` |
|
|
| Plugin migrations | `steward/core/migration_runner.py` | `run_plugin_migrations()` |
|
|
| Core task registration | `steward/app.py` | `_register_core_tasks()` |
|
|
| Scheduler loop | `steward/core/scheduler.py` | `start_scheduler()` |
|
|
|
|
---
|
|
|
|
## Settings System
|
|
|
|
| What | File | Function |
|
|
|---|---|---|
|
|
| All defaults | `steward/core/settings.py` | `DEFAULTS` dict |
|
|
| Read a setting | `steward/core/settings.py` | `get_setting(session, key)` |
|
|
| Write a setting | `steward/core/settings.py` | `set_setting(session, key, value)` |
|
|
| Read all settings | `steward/core/settings.py` | `get_all_settings(session)` |
|
|
| Sync load at startup | `steward/core/settings.py` | `load_settings_sync(db_url)` |
|
|
| Extract SMTP dict | `steward/core/settings.py` | `to_smtp_cfg(settings)` |
|
|
| Extract webhook dict | `steward/core/settings.py` | `to_webhook_cfg(settings)` |
|
|
| Extract Ansible dict | `steward/core/settings.py` | `to_ansible_cfg(settings)` |
|
|
| Extract plugins dict | `steward/core/settings.py` | `to_plugins_cfg(settings)` |
|
|
|
|
---
|
|
|
|
## Plugin System
|
|
|
|
| What | File | Function |
|
|
|---|---|---|
|
|
| Plugin loading | `steward/core/plugin_manager.py` | `load_plugins(app)` |
|
|
| ScheduledTask dataclass | `steward/core/scheduler.py` | `ScheduledTask` |
|
|
| Task runner | `steward/core/scheduler.py` | `start_scheduler(tasks)` |
|
|
|
|
---
|
|
|
|
## Alert Pipeline
|
|
|
|
| What | File | Function |
|
|
|---|---|---|
|
|
| Write metric + evaluate alerts | `steward/core/alerts.py` | `record_metric(session, source_module, resource_name, metric_name, value)` |
|
|
| Init alert pipeline | `steward/core/alerts.py` | `init_alerts(app)` |
|
|
| Rule evaluation | `steward/core/alerts.py` | `_evaluate_rule()` (internal) |
|
|
| Notification dispatch | `steward/core/alerts.py` | `_dispatch_notification()` (internal) |
|
|
| Email + webhook send | `steward/core/notifications.py` | `dispatch_notifications()` |
|
|
|
|
---
|
|
|
|
## Monitors
|
|
|
|
| What | File | Function |
|
|
|---|---|---|
|
|
| Ping a host | `steward/monitors/ping.py` | `ping_check(host, session)` |
|
|
| DNS check a host | `steward/monitors/dns.py` | `dns_check(host, session)` |
|
|
| Data cleanup | `steward/core/cleanup.py` | `run_cleanup(app)` |
|
|
|
|
---
|
|
|
|
## Auth
|
|
|
|
| What | File | Function / Class |
|
|
|---|---|---|
|
|
| Role-based access decorator | `steward/auth/middleware.py` | `@require_role(UserRole.X)` |
|
|
| Login / session handling | `steward/auth/middleware.py` | `login_user()`, `logout_user()` |
|
|
| User count (for first-run) | `steward/auth/middleware.py` | `get_user_count(app)` |
|
|
|
|
---
|
|
|
|
## Data Models
|
|
|
|
| Model | File | Table |
|
|
|---|---|---|
|
|
| `Host` | `steward/models/hosts.py` | `hosts` |
|
|
| `PingResult` | `steward/models/monitors.py` | `ping_results` |
|
|
| `DnsResult` | `steward/models/monitors.py` | `dns_results` |
|
|
| `AlertRule` | `steward/models/alerts.py` | `alert_rules` |
|
|
| `AlertState` | `steward/models/alerts.py` | `alert_states` |
|
|
| `AlertEvent` | `steward/models/alerts.py` | `alert_events` |
|
|
| `PluginMetric` | `steward/models/metrics.py` | `plugin_metrics` |
|
|
| `AnsibleRun` | `steward/models/ansible.py` | `ansible_runs` |
|
|
| `User` | `steward/models/users.py` | `users` |
|
|
| `AppSetting` | `steward/models/settings.py` | `app_settings` |
|
|
| `TraefikMetric` | `plugins/traefik/models.py` | `traefik_metrics` |
|
|
| SQLAlchemy `Base` | `steward/models/base.py` | (shared declarative base) |
|
|
|
|
---
|
|
|
|
## HTTP Routes
|
|
|
|
| URL pattern | Blueprint | File |
|
|
|---|---|---|
|
|
| `/` (dashboard) | `dashboard_bp` | `steward/dashboard/routes.py` |
|
|
| `/auth/login`, `/auth/logout` | `auth_bp` | `steward/auth/routes.py` |
|
|
| `/hosts/` | `hosts_bp` | `steward/hosts/routes.py` |
|
|
| `/ping/`, `/ping/rows`, `/ping/settings` | `ping_bp` | `steward/ping/routes.py` |
|
|
| `/dns/`, `/dns/rows` | `dns_bp` | `steward/dns/routes.py` |
|
|
| `/alerts/` | `alerts_bp` | `steward/alerts/routes.py` |
|
|
| `/ansible/` | `ansible_bp` | `steward/ansible/routes.py` |
|
|
| `/settings/` | `settings_bp` | `steward/settings/routes.py` |
|
|
| `/plugins/traefik/`, `/plugins/traefik/widget` | `traefik_bp` | `plugins/traefik/routes.py` |
|
|
| `/health` | (inline) | `steward/app.py` |
|
|
|
|
---
|
|
|
|
## Templates
|
|
|
|
| Template | Purpose |
|
|
|---|---|
|
|
| `steward/templates/base.html` | Layout, navigation, full CSS design system |
|
|
| `steward/templates/dashboard/index.html` | Dashboard with stat strip and widget grid |
|
|
| `steward/templates/ping/rows.html` | HTMX fragment: ping pill rows (shared by dashboard and /ping/) |
|
|
| `steward/templates/ping/index.html` | Full /ping/ page |
|
|
| `steward/templates/dns/rows.html` | HTMX fragment: DNS status rows |
|
|
| `steward/templates/dns/index.html` | Full /dns/ page |
|
|
| `plugins/traefik/templates/traefik/widget.html` | HTMX fragment: Traefik dashboard widget |
|
|
| `plugins/traefik/templates/traefik/index.html` | Full Traefik detail page |
|
|
|
|
---
|
|
|
|
## Migrations
|
|
|
|
| Location | Covers |
|
|
|---|---|
|
|
| `steward/migrations/versions/` | Core schema (hosts, users, monitors, alerts, app_settings) |
|
|
| `plugins/traefik/migrations/versions/` | `traefik_metrics` table |
|
|
| `alembic.ini` | Alembic config; `version_locations` lists all migration directories |
|
|
|
|
---
|
|
|
|
## MCP server and API tokens
|
|
|
|
| What | File | Function / Class |
|
|
|---|---|---|
|
|
| Mount `/mcp` (ASGI dispatch, bearer auth, DB gate) | `steward/mcp/server.py` | `mount_mcp(app)` |
|
|
| Server, role registry, refusals | `steward/mcp/server.py` | `StewardMCPServer`, `register_tool()`, `refusal()` |
|
|
| Plugin tools and overview findings | `steward/mcp/server.py` | `register_plugin(name, module)` |
|
|
| Caller and app inside a tool | `steward/mcp/_context.py` | `current_caller()`, `mcp_app()` |
|
|
| Core tool modules | `steward/mcp/tools/` | `register_all()`; one module per area |
|
|
| Response conventions | `steward/mcp/tools/_shape.py` | `iso`, `age_s`, `bounded`, `lookback`, `summarize`, `pick` |
|
|
| Audit a write as "<user> via MCP" | `steward/mcp/tools/_audit.py` | `audit_mcp()` |
|
|
| "What is wrong now" | `steward/mcp/tools/overview.py` | `get_overview()` |
|
|
| Playbooks, runs, schedules, alert actions | `steward/mcp/tools/automation.py` | `run_playbook()`, `wait_for_run()`, … |
|
|
| Monitor validation (forms and tools) | `steward/monitors/service.py` | `monitor_fields()`, `build_config()` |
|
|
| Alert rule / window validation | `steward/alerts/service.py` | `rule_fields()`, `window_fields()`, `acknowledge()` |
|
|
| Docker and host-agent tools | `plugins/docker/mcp_tools.py`, `plugins/host_agent/mcp_tools.py` | `register_tools()`, `mcp_overview()` |
|
|
| Token model | `steward/models/api_tokens.py` | `ApiToken` |
|
|
| Mint, resolve, revoke tokens | `steward/core/api_tokens.py` | `create_token()`, `resolve_token()`, `revoke_token()` |
|
|
| Token management page and connect card | `steward/ai_access/routes.py`, `steward/templates/ai_access/` | `ai_access_bp` |
|