Linux VedaOps MCP

linux-vedaops-mcp is the governed development control plane for VedaOps projects on Chaz's Pop!_OS workstation.

It lets authorized agents understand, inspect, search, patch, test, lint, and coordinate registered software projects without exposing a general shell or raw filesystem proxy.

Current status

The fifteen-tool development core is implemented:

• registry and orientation: vedaops_server_info, projects_list, project_get, project_context_get, and project_health;
• project inspection: project_tree, project_file_read, project_search, project_git_status, and project_git_diff;
• coordination: project_lease_acquire, project_checkpoint_create, and project_lease_release;
• implementation: project_patch_apply and project_task_run.

Project discovery never grants authority. The trusted operator registry lives outside every managed root, while project manifests can only narrow its grants. Read tools are path-confined and bounded, and repository-local Git configuration is treated as untrusted input. File changes and tasks require explicit granular capabilities, authenticated or controlled-launch identity, an exclusive lease, the expected Git HEAD, and durable audit evidence.

Patch input is textual unified diff only. Task argv comes only from the trusted project registry; callers cannot submit shell commands or arbitrary arguments.

Stdio and authenticated loopback Streamable HTTP transports are tested. Hosted ChatGPT access runs through a dedicated OpenAI Secure MCP Tunnel and enabled user-level systemd service.

Development

uv sync
uv run pytest -q
uv run ruff check .

Run locally over stdio:

VEDAOPS_AGENT_ID=codex uv run vedaops-mcp stdio

The HTTP entrypoint remains loopback-only. Configure either a private VEDAOPS_HTTP_TOKENS_FILE containing distinct token-to-agent mappings, or a single VEDAOPS_HTTP_TOKEN plus VEDAOPS_HTTP_TOKEN_IDENTITY:

uv run vedaops-mcp http

It listens on http://127.0.0.1:8765/mcp by default. Never commit credentials. Hosted ChatGPT uses the stdio-backed Secure MCP Tunnel profile, not this loopback HTTP entrypoint.

Operator configuration

Install config/projects.toml.example as ~/.config/vedaops/projects.toml with mode 0600, then edit the external copy. Registry, settings, state, and credential files must remain outside every managed repository; trusted operator files may not be symlinks.

Stable naming

• Repository: linux-vedaops-mcp
• Python package: vedaops_mcp
• Console command: vedaops-mcp

Documents

• docs/project-onboarding.md — register and safely enable a managed project
• docs/development-workflow.md — normal inspect, lease, patch, verify workflow
• docs/project-extensions.md — context, tasks, adapters, and project-specific behavior
• CONTEXT.md — current operational handoff and exact next action
• AGENTS.md — canonical agent rules
• docs/architecture.md — boundaries and internal design
• docs/security.md — threat model and controls
• docs/core-coordination.md — lease, checkpoint, and audit contract
• docs/operations.md — installed service and state runbook
• docs/client-setup.md — tested client connection record
• docs/tool-catalog.md — complete governed tool catalog
• docs/decisions/ — accepted architecture decisions

Start with the onboarding guide when adding a repository. Start with the development workflow when using an already registered project.