Skip to main content
Glama
Agent Workstation
by zix-chen

Agent Workstation

简体中文 · Security · Architecture · Client setup

Bring an MCP client into your developer workflow. Prefer APIs and CLIs over clicking screens.

A small, opinionated adapter built on Coding Tools MCP. It adds explicit workstation trust, multi-repository context discovery, a lazy rules/skills/recipes entry point, and bounded command previews. It does not implement a new model, agent loop, SQL engine, browser driver, or secret vault.

What is actually new?

Inherited from Coding Tools MCP

Added here

Files, patches, search, Git, process lifecycle, MCP transport

Explicit workspace / trusted-workstation launch modes

Output retention, references, pagination

8 KiB default head/tail preview with stderr budgeting

Root instruction loading

Bounded multi-repo discovery and target-path rule lookup

Generic command execution

workspace_guide: on-demand skill metadata and opt-in recipe routing

The adapter pins upstream commit bedb632e1afd2e9ec9b268a50fe0b04695c22c64. Its package metadata says 0.3.0; this is not a claimed upstream 0.5 release. Upstream-private imports/hooks are isolated in agent_workstation/compat/coding_tools.py. A mismatched upstream build fails at startup rather than silently running an untested adapter.

Related MCP server: MCP Lab

Install and try

Requirements: Python 3.11+, Git; macOS or Linux. Your own MCP client supplies the model. No Codex installation or model API key is required by this server. The package is installed from GitHub; it is not published to PyPI in this release.

# An isolated environment; does not alter another MCP installation.
python3 -m venv .venv
. .venv/bin/activate
python -m pip install "git+https://github.com/zix-chen/agent-workstation.git@v0.1.1"
agent-workstation --workspace /path/to/repository --doctor
agent-workstation --workspace /path/to/repository --stdio

Generic stdio MCP configuration (use an absolute executable path):

{
  "mcpServers": {
    "agent-workstation": {
      "command": "/absolute/path/to/.venv/bin/agent-workstation",
      "args": ["--workspace", "/absolute/path/to/work", "--mode", "workspace", "--stdio"]
    }
  }
}

Ask the client: “Call workspace_guide for this repository, read the relevant rules/skill, then review this change. Report evidence and what you did not verify.”

Explicit workstation access

agent-workstation --workspace "$HOME/work" --mode trusted-workstation --stdio

This gives commands your real HOME, local developer configuration, network access and access outside the workspace. Commands can read secrets, modify files and operate services with your user privileges. It is NOT secret isolation or protection from prompt injection. Use trusted code and a trusted agent, or a disposable account/VM with reduced credentials.

Default workspace mode retains upstream safe command gates, isolated HOME and structured path validation. It is not a complete OS sandbox, especially on macOS. Repository rules are workflow guidance, not permission enforcement. See SECURITY.md.

Rules, skills and recipes

work/
  AGENTS.md
  repo-a/
    AGENTS.md
    .agents/skills/review/SKILL.md
  repo-b/
    src/AGENTS.md

workspace_guide(path="repo-a") returns applicable rule paths and skill name/description/hash. It does not inject every skill's full body. The agent selects and fully reads the smallest relevant skill. Same-name skills retain their source paths. Startup avoids recursive workspace walks, skips generated/worktree directories and uses Git metadata at actual repository roots. Target-path lookup can still find rules under a skipped tree when explicitly selected.

Recipes are explicitly loaded TOML, never auto-executed:

agent-workstation --workspace "$PWD/examples/demo-service"   --config "$PWD/examples/demo-service/workstation.toml" --stdio

See the runnable example and configuration contract. External skill roots require explicit config and trusted-workstation mode. kubectl, mysql, redis-cli, cloud CLIs and their credentials are user-managed, not bundled integrations.

Reproduce the demo and benchmark

git clone https://github.com/zix-chen/agent-workstation.git
cd agent-workstation
python3 -m venv .venv
. .venv/bin/activate
python -m pip install -e '.[dev]'
python -m unittest discover -s tests -v
python scripts/demo.py
python scripts/benchmark_output.py
python scripts/check_release.py

The demo uses a temporary copy of a fake backend, calls real MCP tools, checks a local HTTP health endpoint, diagnoses a missing demo configuration, and verifies the corrected process. It uses no private infrastructure or model credentials. It is a deterministic integration demo, not a claim of autonomous model task success.

The benchmark reports output bytes and serialized response bytes. It does not measure model tokens, subscription quotas, speedups, or dollars saved. Explicit output arguments override defaults. Follow read_output references when previews truncate; retained output can expire or lose its middle segment. Save an authorized log file for durable/full logs.

HTTP and remote clients

An optional loopback HTTP listener requires a bearer token even on localhost:

# Supply a random 32+ character secret through your process supervisor/secret manager.
# Never put the real value in this repo, the README, or a model prompt.
agent-workstation --workspace /path/to/work --transport http --port 8765
# Reads AGENT_WORKSTATION_HTTP_TOKEN; startup refuses an absent/short token.

Remote access requires your own authenticated HTTPS transport and a compatible client. OAuth registration and tunnels are not implemented by this V1. A generic stdio configuration is not a ChatGPT web connection. See client setup and verification boundaries. No public listener or tunnel is installed automatically.

A real run transcript is available in docs/demo-output.txt.

Scope and status

V0.1 is a small developer-tool release, not an enterprise platform. Computer/browser automation, GUI secret filling, company-specific integrations, production deployment automation and a plugin marketplace are intentionally excluded. See validation for actual test results.

Design decisions cover the adapter architecture, trust model, and verification boundaries.

License and attribution

Apache-2.0. Built on Coding Tools MCP, Copyright 2026 Coding Tools MCP Contributors. See NOTICE and THIRD_PARTY_NOTICES.md. No private repository history, employee accounts, business code or production configuration is distributed.

The pinned upstream read_file also caps a page at 2,000 lines. Raising max_bytes does not remove that cap; use next_start_line to read the remaining pages.

Available Tools

19 tools
apply_changesApply changesA
Destructive

Apply line-addressed file changes atomically. Prefer this over apply_patch when you know the line numbers: nothing has to match. Each change names an action (create, write, edit, delete, move, copy), and a path. write is an upsert: it needs the revision read_file reported when the path exists, but may omit it when creating a missing path. edit, delete, move, and copy always need that revision; create rejects it and asserts absence. edit takes line operations (replace, delete, insert_after, insert_before) whose numbers all refer to the file as read, not to the result of earlier edits in the same call. content is whole lines: "" is zero lines and a trailing newline adds a blank line. One path per call; use apply_patch to chain several edits onto one file. Example: {"changes":[{"action":"edit","path":"app.py","revision":"","edits":[{"op":"replace","start_line":10,"end_line":12,"content":"new line"}]}]}

Inputs: changes (required), dry_run, idempotency_key. Returns: ok, clean, error, dry_run, +8 more

apply_patchApply patchA
Destructive

Stage, validate, and atomically apply a V4A patch envelope. Each hunk locates itself by its context, so the context must be unique in the file; when it is not, add a scope header (@@ def my_function) naming the enclosing block, or add '*** End of File' to anchor the hunk at the end. A blank context line may be written as "" or as a single space. Matching is graded exact, then ignoring trailing whitespace, then ignoring indentation width, and the grade actually used comes back as match_quality. Success returns each file's revision, total_lines, and changed_ranges. Several updates to one path in one envelope chain in order. Full format reference: docs/tools-and-schemas.md. Example: *** Begin Patch *** Update File: app.py @@ -old +new *** End Patch

Inputs: patch (required), dry_run, idempotency_key. Returns: ok, clean, error, dry_run, +8 more

check_exec_environmentCheck exec environmentA
Read-onlyIdempotent

Return lightweight exec_command sandbox and environment status known to the server.

Inputs: no named parameters. Returns: ok, error, warnings, workspace, +3 more

exec_commandExecute commandA
Destructive

Run a bounded command under runtime policy. Pass workdir explicitly for reconnect-safe paths. yield_time_ms is only how long this call waits (default 10s); timeout_ms is the total process lifetime (default 300s). A command still running when the call returns keeps running under its command_id; poll it with write_stdin or read_output. Example: {"cmd":"pytest -q","workdir":".","yield_time_ms":30000}. Retained output is bounded per stream; for very large output redirect to a file (cmd > out.log 2>&1) and page it with read_file or search_text.

Inputs: cmd (required), cwd, env, tty, +7 more. Returns: ok, error, signal, status, +31 more

git_blameGit blameC
Read-onlyIdempotent

Return bounded git blame metadata for a workspace file.

Inputs: path (required), rev, end_line, max_lines, +1 more. Returns: ok, path, error, lines, +2 more

git_diffGit diffB
Read-onlyIdempotent

Return unified git diff for workspace changes. Untracked files are included as additions by default, so a newly created file is verifiable here.

Inputs: path, paths, staged, unstaged, +3 more. Returns: ok, diff, error, files, +3 more

git_logGit logC
Read-onlyIdempotent

Return recent git commits with bounded structured metadata.

Inputs: ref, path, skip, max_count. Returns: ok, error, commits, is_repo, +2 more

git_showGit showC
Read-onlyIdempotent

Return bounded git show output for a revision.

Inputs: rev, path, paths, max_bytes, +2 more. Returns: ok, error, files, content, +2 more

git_statusGit statusB
Read-onlyIdempotent

Return git working tree status for the workspace.

Inputs: path, max_entries, include_untracked. Returns: ok, error, branch, entries, +3 more

kill_commandKill commandC
Destructive

Terminate a server-managed command by command_id. Example: {"command_id":"abc","signal":"KILL"}.

Inputs: command_id (required), signal, wait_ms, verbosity, +3 more. Returns: ok, error, killed, signal, +33 more

list_dirList directoryC
Read-onlyIdempotent

List directory entries inside the configured workspace.

Inputs: path, sort, max_depth, recursive, +3 more. Returns: ok, path, error, entries, +5 more

list_filesList filesC
Read-onlyIdempotent

List workspace files using glob filters.

Inputs: glob, path, sort, patterns, +4 more. Returns: ok, path, error, files, +5 more

read_fileRead fileB
Read-onlyIdempotent

Read a UTF-8 text file slice inside the configured workspace.

Inputs: path (required), encoding, end_line, max_bytes, +2 more. Returns: ok, path, error, content, +15 more

read_outputRead outputA
Read-onlyIdempotent

Read retained command output using an output_ref returned by exec_command/write_stdin. Each stream retains the earliest output (head) plus the most recent output (rolling tail); bytes between them may be evicted and are reported via evicted_gap_bytes. Example: {"output_ref":"command:abc:stdout","offset":0,"limit":4096}.

Inputs: output_ref (required), limit, offset, stream. Returns: ok, error, limit, offset, +20 more

search_textSearch textC
Read-onlyIdempotent

Search UTF-8 workspace files for text or regex matches.

Inputs: query (required), glob, path, regex, +6 more. Returns: ok, error, query, engine, +8 more

server_infoServer infoA
Read-onlyIdempotent

Return server, workspace, project-context, auth, policy, and fixed-tool metadata.

Inputs: no named parameters. Returns: ok, error, tools, server, +5 more

view_imageView imageC
Read-onlyIdempotent

Return a workspace image as MCP image content.

Inputs: path (required), max_bytes, max_width, max_height, +1 more. Returns: ok, path, bytes, error, +5 more

workspace_guideFind target rules, skills and recipesA
Read-onlyIdempotent

Find applicable repository instructions and skill metadata for a target path. Read the selected full files before acting; no execution or permission grant.

Inputs: path. Returns: ok, error

write_stdinWrite stdinB

Poll or interact with a running command by command_id. Empty chars wait for output; non-empty chars writes to stdin. Example: {"command_id":"abc","chars":"","yield_time_ms":10000}.

Inputs: command_id (required), chars, verbosity, preview_bytes, +2 more. Returns: ok, error, signal, status, +30 more

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 19 tools

    Disambiguation4/5

    Most tools have clearly distinct resource+action purposes, such as file reading/listing/searching versus command execution and Git inspection. The main overlap is between apply_patch and apply_changes, which both modify files and could require an agent to read descriptions carefully before choosing one.

    Naming Consistency4/5

    Tool names consistently use snake_case and mostly follow predictable prefixes such as read_, list_, search_, apply_, git_, and exec_. Minor deviations exist (server_info and workspace_guide are noun-based rather than verb_noun), but the naming remains readable and coherent.

    Tool Count4/5

    The 19 tools fit a broad workspace-agent scope covering file operations, patching, command execution, process management, Git inspection, image viewing, and guidance. It is slightly on the heavy side relative to a typical 3-15 tool server, but each cluster addresses a real capability.

    Completeness4/5

    The surface covers core workspace lifecycle operations: read/list/search, create/write/edit/delete via apply_changes, patching via apply_patch, command execution and management, and key Git read operations. Minor gaps such as dedicated Git commit/stage tools or simple directory metadata operations can be handled through exec_command, so the set is largely complete for its purpose.

    Maintenance

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables MCP clients to execute commands, edit files, run Git workflows, and perform validated independent reviews in real development environments through Docker-based runtimes with separated developer and auditor permissions.
      MIT
    • A
      license
      D
      quality
      C
      maintenance
      Enables controlled local developer operations including file and process management, shell execution, SSH, WSL, Docker, Git, browser and desktop automation, media processing, and asynchronous jobs through MCP.
      146
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables teams to onboard remote MCP servers, enforce function-level permissions and credential modes, and let developers expose permitted tools through a unified MCP endpoint with search and execute functions while auditing usage.
      MIT