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 sixteen-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, project_git_diff, and project_git_compare;

• coordination: project_checkpoint_create;

• implementation: project_patch_apply, project_git_commit, project_review_run, and project_task_run. The review tool patches and tests an automatically removed copy while leaving the authoritative dirty tree unchanged.

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, the expected Git HEAD, per-call project locking, 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. Task executable lookup includes the operator's ~/.local/bin, and project health reports configured executables that cannot be resolved before execution.

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.

Related MCP server: AI Knowledge Center MCP

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, 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 — mutation, 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.