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

## Development

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

Run locally over stdio:

```bash
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`:

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