workspace-mcp
A workspace-scoped filesystem and project-memory MCP server: it reads, writes, edits, patches and searches files inside one or more named project roots, and keeps lightweight state (activity journal, notes, changes, tasks) so a new chat can re-orient itself.
Files —
read_file(1-based line numbers, offset/limit),write_file(create/overwrite, auto parent dirs),edit_file(exact-string replace, optionalreplaceAll),patch(multi-file, all-or-nothing edits).Search & discovery —
grep(JS regex, globinclude, case-insensitive, capped results) andlist_files(globpattern, depth/limit caps, dirs marked/).Workspaces —
workspace_listshows name, root, primary marker and state/active-change; every tool takes an optionalworkspaceargument (defaults to primary).Notes & history —
work_logreads the automatic journal of mutating operations (filter by time, path, change);remember/recallstore and query persistent tags notes for context recovery.Git (read-only, no shell needed) —
git_status(branch + porcelain) andgit_diff(staged/unstaged/stat, path-filtered).Tracked work —
change_create,change_activate,change_doc(proposal/spec/design/notes),change_status(full view + suggested next action, or list all),task_add,task_update(all-or-nothing, capped at 100),constraint_add.Safety guardrails — all paths confined to the selected workspace root, symlinks never followed outside, binaries and
.git/node_modules/.cache/.workspace-mcpskipped, errors sanitized to one short message.Not available in this schema — no command execution;
run_command,start_job,job_statusandjob_killare opt-in and not registered here (19 tools exposed).
Provides read-only Git repository integration with git_status and git_diff tools, allowing agents to inspect branch status, working tree changes, and diffs within the workspace.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@workspace-mcp show me the current git status and recent work log for my project"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
workspace-mcp
A Model Context Protocol (MCP) server that gives an agent in any MCP-capable chat client a small, safe filesystem toolkit scoped to one or more named project workspaces: read, write, edit, patch, grep and list. The point is to remove copy-paste: instead of asking the user to paste file contents into the chat, the agent reads, searches and edits files directly through typed tools with a containment boundary that rejects everything outside the selected workspace root. Since v1.5.0 one server process can serve several projects at once, and every path or state tool takes an optional workspace argument.
The tool set is modelled after opencode's built-in tools (read, write, edit, patch, grep, glob), plus an opt-in run_command tool for tests, linters and builds. Command execution is off by default and only registers when you ask for it with --shell (allowlist), --shell-any (unrestricted) or a config file that sets shell.mode.
On top of that, the server keeps a small workspace-local memory: an automatic activity journal plus persistent notes (work_log, remember, recall), and read-only git_status / git_diff tools that work without the shell, so a new chat can recover context on its own.
Runtime: Node.js >= 22.13, ESM only
Transports: stdio (default) and Streamable HTTP at
/mcpZero runtime dependencies beyond
@modelcontextprotocol/sdkandzod
Documentation
docs/ARCHITECTURE.md - module map, request flow, state model and design decisions.
docs/SECURITY.md - trust model, path containment, command execution and HTTP exposure.
CHANGELOG.md - release history.
Related MCP server: Student MCP File-Server Connector
Requirements
Node.js >= 22.13 (the harness session store uses the built-in
node:sqlitemodule, available unflagged from Node 22.13;node:sqliteis still experimental in the 22.x line and its API may change)pnpm (or npm) for building from source
Install, build, run
pnpm install
pnpm build
# stdio (default) - what MCP clients launch
node dist/index.js --root /absolute/path/to/project
# Streamable HTTP with bearer token
node dist/index.js --root /absolute/path/to/project --http --port 3333 --token "$MCP_TOKEN"CLI reference
Option | Default | Description |
|
| Primary workspace root, registered as the workspace named |
| Register an additional named workspace. Repeatable. Names match | |
| discovery | Use an explicit JSON config file (see Configuration file). The file must exist and be valid or the server exits |
| off | Serve Streamable HTTP at |
|
| HTTP bind host. |
|
| HTTP bind port. |
|
| When set, every HTTP request must send |
| off | Enable |
| off | Enable the same tools in unrestricted mode (any executable). Implies |
| Add executables to the allowlist. Comma-separated ( | |
| Print usage. | |
| Print the version. |
Shell environment fallbacks (CLI flags take precedence): WORKSPACE_MCP_SHELL=1 enables allowlist mode, WORKSPACE_MCP_SHELL_MODE=allowlist|any sets the mode (setting it also enables the tool), WORKSPACE_MCP_SHELL_ALLOW=git,docker extends the allowlist, WORKSPACE_MCP_SHELL_DENY=docker always rejects those executables.
Notes:
In stdio mode the server never writes to stdout (that is the protocol stream). All diagnostics go to stderr.
SIGINT/SIGTERMtrigger a graceful shutdown (transports and HTTP server are closed).If
--httpis used without a token on a non-loopback host, the server prints a loud security warning to stderr.
Configuration file
Since v1.6.0 one optional JSON file can supply defaults for workspaces, shell execution, transport and state. It is a defaults layer, never a replacement, and with no file present the behavior is identical to previous versions. Editor autocomplete is available through schemas/config.schema.json.
Discovery (first match wins)
--config <path>— explicit. If the file is missing or invalid the server exits1with a clear message../workspace-mcp.config.jsonin the process working directory.$XDG_CONFIG_HOME/workspace-mcp/config.json, or~/.config/workspace-mcp/config.jsonwhenXDG_CONFIG_HOMEis unset.
A discovered file that exists but is invalid is a startup error, never silently ignored: a broken config must be loud. An explicit --config path wins even when a cwd or global file also exists.
Full example
{
"$schema": "https://raw.githubusercontent.com/MarcoCaamal/workspace-mcp/main/schemas/config.schema.json",
"workspaces": { "default": "/abs/path", "api": "/abs/other" },
"shell": {
"mode": "allowlist",
"allow": ["pnpm", "npm", "node", "git"],
"deny": ["docker"],
"timeoutMs": 300000,
"maxRuntimeMs": 3600000
},
"transport": { "type": "stdio", "host": "127.0.0.1", "port": 3333 },
"state": { "journalMaxBytes": 10485760 }
}Rules that apply to the whole file:
$schemais accepted and ignored.Unknown keys anywhere are rejected (typo protection), and a
tokenkey anywhere is refused withtoken must not be stored in the config file; use MCP_TOKEN or --token. Secrets never belong in this file.workspacesis a map name → path. Names match^[a-z0-9][a-z0-9_-]*$; paths are resolved to absolute realpaths and must exist (relative paths resolve against the directory containing the config file). The workspace nameddefaultis primary when present, otherwise the first key.shell.modeis"allowlist"or"any". Its presence enables the shell tools, as if--shellwas passed.shell.allow/shell.denyare executable names (basenames are extracted;"/usr/bin/docker"meansdocker).shell.timeoutMs(1000–600000) becomes the defaultrun_commandtimeout when the call omitstimeoutMs;shell.maxRuntimeMs(1000–7200000) becomes the defaultstart_jobmax runtime. Per-call arguments still win and are validated against the same caps.transport.type,transport.hostandtransport.portbehave exactly like--http,--hostand--port;transport.type: "http"starts the HTTP server.state.journalMaxBytesis applied as the default forWORKSPACE_MCP_JOURNAL_MAX_BYTES.
Precedence
The same order applies everywhere: CLI flags > environment variables > config file > built-in defaults.
Setting | CLI | Env | Config | Built-in default |
Workspaces |
| — |
| cwd as |
Shell on/off |
|
|
| off |
Shell mode |
|
|
|
|
Shell allow |
|
|
|
|
Shell deny | — |
|
| none |
|
| — |
|
|
|
| — |
|
|
Transport |
| — |
| stdio / |
Journal rotation | — |
|
| 5 MiB |
HTTP bearer token |
|
| never | none |
Notes on the merge:
Workspaces merge by name: config entries come first, then
--workspace name=pathentries override same-name entries or add new ones, so a CLI workspace can extend the file's set without retyping it.--rootmaps to namedefaultand overrides any configdefault.Allowlists are a union of the built-in defaults, config, env and CLI (all reduced to basenames), so
--shell-allownever narrows anything. To restrict, useshell.deny.Deny is a restriction: it is checked before the allowlist in both
allowlistandanymode, and no CLI flag can remove it. A denied command fails withcommand denied by configuration: <name>.The HTTP bearer token is deliberately not configurable through the file.
Tools
Every tool that takes a path/cwd or reads or writes workspace state also accepts an optional workspace argument (see Multiple workspaces); it defaults to the primary workspace.
Tool | Arguments | Behavior |
|
| Returns text with 1-based line numbers as |
|
| Creates parent directories, overwrites existing files. Returns |
|
| Exact string replacement. Empty |
|
| All-or-nothing: validates every edit against the current (in-memory) file contents first. If any edit fails, no file is written and the failing index is reported as |
|
| Read-only. Newest-first automatic journal of the mutating operations ( |
| none | Read-only. Lists the configured workspaces: name, absolute root path, |
|
| Appends a persistent note under |
|
| Read-only. Newest-first notes rendered as |
|
| Returns |
|
| Sorted workspace-relative entries; directories carry a trailing |
|
| Opt-in. Runs |
|
| Opt-in. Starts the command detached and returns immediately with a |
|
| Read-only. With |
|
| Sends |
|
| Read-only, no shell required. Runs |
|
| Read-only, no shell required. Runs |
|
| Creates a tracked change: JSON record plus documents directory, id = kebab-case slug of the title (deduped with |
|
| Makes an existing change active. While active, every journal entry is tagged with its id and the other change tools default to it. Unknown id is a clear error. |
|
| Writes |
|
| Read-only. The single re-orientation call: full view of one change (docs present/missing with byte sizes, tasks grouped by status, constraints, the last 10 tagged journal entries, and a derived suggested next action) or, with |
|
| Appends a task with a sequential id ( |
|
| All-or-nothing: every task id and status is validated before anything is written; one bad entry changes nothing on disk and the error lists the bad ids. A |
|
| Appends a constraint to the change and returns the count plus the full list. Constraints are shown by |
All tools:
accept workspace-relative paths (absolute paths inside the root also work) and reject anything that resolves outside the root;
return workspace-relative paths;
fail with
{ isError: true }and exactly one short, actionable message - never a stack trace or rawENOENTdump;annotate themselves for clients:
readOnlyHint: trueforread_file,grep,list_files,work_log,recall,git_status,git_diffandchange_status;destructiveHint: trueforwrite_file,edit_file,patch;readOnlyHint: false, destructiveHint: true, openWorldHint: truefor the opt-inrun_command,start_jobandjob_kill;readOnlyHint: true, openWorldHint: falseforjob_status; andreadOnlyHint: falseforrememberand the six mutating change tools (change_create,change_activate,change_doc,task_add,task_update,constraint_add) - they append to state under.workspace-mcp/and change no workspace data.
Glob syntax (used by grep.include and list_files.pattern): **, *, ?, {a,b} and [abc] character classes (including [!abc]). Patterns without a / match the file name at any depth, so *.ts matches src/index.ts.
Client configuration
Claude Desktop (Linux)
Config file: ~/.config/Claude/claude_desktop_config.json (macOS and Windows use their own platform paths). Restart Claude Desktop after editing.
{
"mcpServers": {
"workspace-mcp": {
"command": "node",
"args": ["/path/to/workspace-mcp/dist/index.js", "--root", "/path/to/project"]
}
}
}Cursor
Config file: ~/.cursor/mcp.json (global) or .cursor/mcp.json (per project).
{
"mcpServers": {
"workspace-mcp": {
"command": "node",
"args": ["/path/to/workspace-mcp/dist/index.js", "--root", "${workspaceFolder}"]
}
}
}opencode
opencode.json (or global ~/.config/opencode/opencode.json) - local servers use the mcp key with type: "local":
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"workspace-mcp": {
"type": "local",
"command": ["node", "/path/to/workspace-mcp/dist/index.js", "--root", "/path/to/project"],
"enabled": true
}
}
}For the HTTP transport, use a remote entry with a header:
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"workspace-mcp": {
"type": "remote",
"url": "http://127.0.0.1:3333/mcp",
"oauth": false,
"headers": { "Authorization": "Bearer ${MCP_TOKEN}" }
}
}
}ChatGPT desktop app
Settings -> MCP servers -> Add server -> choose STDIO, then provide the name plus the command and arguments (node /path/to/workspace-mcp/dist/index.js --root /path/to/project), save and restart. The desktop app (and Codex CLI / IDE extension, which share the config in ~/.codex/config.toml) also supports Streamable HTTP servers and bearer token authentication.
Remote HTTP clients that support custom headers
Any client that can set headers may connect to the HTTP transport with Authorization: Bearer <token>:
node dist/index.js --root /srv/project --http --host 127.0.0.1 --port 3333 --token "$MCP_TOKEN"
curl -s -X POST http://127.0.0.1:3333/mcp \
-H "Authorization: Bearer $MCP_TOKEN" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'The endpoint is stateless: every POST creates a fresh server instance, so no session headers are needed. GET/DELETE /mcp return 405, and a missing or wrong token returns 401 with WWW-Authenticate: Bearer.
ChatGPT web and other hosted web clients - read this
Hosted web clients (ChatGPT web, claude.ai connectors, and similar) are a different story:
They require a publicly reachable HTTPS Streamable HTTP endpoint.
localhostis not reachable from them.ChatGPT custom connectors authenticate through OAuth 2.1 (plus its own connector review flow). A static
Authorization: Bearerheader - which is all this server implements in v1 - is not an option there.Therefore v1 HTTP mode targets local testing and clients that accept custom headers (Cursor remote entries, opencode remote entries, Claude Code via
claude mcp add --transport http ... --header "Authorization: Bearer ...", API playgrounds, scripts). For ChatGPT web you would need to add an OAuth 2.1 layer around this server, which is out of scope for v1.
If you want to test with a public URL anyway, a tunnel works:
# WARNING: this publishes full read/write access to the --root directory on the
# public internet. The bearer token is the only thing protecting it. Use a long
# random token, a throwaway root, and shut the tunnel down when you are done.
cloudflared tunnel --url http://127.0.0.1:3333Then point the client at https://<random>.trycloudflare.com/mcp with the bearer header.
Multiple workspaces
Since v1.5.0 one server process can serve several projects at once. Each workspace is a named root with its own state under <root>/.workspace-mcp/:
node dist/index.js --root /path/to/project --workspace api=/path/to/other-project--root <dir>registers the primary workspace nameddefault.--rootalone behaves exactly as before (fully backward compatible).--workspace <name>=<path>is repeatable and registers another workspace. Names must match^[a-z0-9][a-z0-9_-]*$. A missing=, an invalid name, a duplicate name (including--workspace default=...next to--root) or a non-existent path aborts startup with a clear message.Workspaces can also be declared in the config file
workspacesmap. CLI entries override same-name config entries and add new ones;--rootoverrides a configdefault.With only
--workspaceflags, the first one is primary unless one is literally nameddefault. With no flags at all, the current working directory is the single primary workspace nameddefault.Every path or state tool accepts an optional
workspaceargument, for exampleread_file { "path": "src/index.ts", "workspace": "api" }. Omitting it targets the primary workspace. An unknown name fails withunknown workspace "X". Available: ....workspace_list(read-only) shows every workspace: name, absolute path,(primary)marker, whether<root>/.workspace-mcpexists, and the active change id whenstate.jsonexists.Isolation is per root. Paths are confined to the selected root, and the journal, notes and change tracking live under the selected root's
.workspace-mcp/. A../escape is rejected relative to the selected workspace even when the same path would be valid in another one.Shell tools follow the selection.
run_commandandstart_jobresolvecwdagainst the selected workspace, andgit_status/git_diffrungit -C <selected root>.
ChatGPT guided entry
New ChatGPT operators start here: docs/CHATGPT_ENTRY.md
(pinned preset scripts/tunnel.sh --preset chatgpt --root /path/to/project,
session convention, shell opt-in). Honesty note for this slice: the legacy
writers change_create, change_doc, task_add, work_log, and remember
create repo-local state under <root>/.workspace-mcp/; the no-artifacts
workflow is not available in this slice.
Harness sessions (stateful SDD flow)
Enable with the config file (harness.session: true, optional
harness.dbPath, or WORKSPACE_MCP_HARNESS_DB); both harness flags default
off. Eight tools are registered: session_start, session_end,
work_start, session_resume, stage_write, task_write, checkpoint,
harness_status.
Quick path:
session_start(binds one primary workspace, omitworkspaceto use the configured primary) → opaque session token.work_start { session }→ work token for one unit of work.stage_write/task_writeper stage, thencheckpointcarrying the stored artifact id, thenharness_statusfor the derived next action.session_resume { session, work }on any later turn, including after a server restart: identity is by explicit token only.
Details:
Topic | Contract |
Stages |
|
Workspace binding | Every record pins its canonical workspace; an explicit |
Identity limits | Tunnel, connection, and profile identifiers are never session identity. The shared HTTP bearer gates transport access only; within an authenticated tunnel, possession of a session/work token controls that session. There is no per-caller identity and no stronger conversation-isolation claim. |
Storage | Sessions, works, stage/task bodies, checkpoints, and summaries live only in the outside-repo store ( |
Legacy separation | The legacy writers above still write repo-local state and serve the legacy flow only; the harness flow never calls them for new stage/task data. |
Restarts | Session/work/stage state survives restarts via the store; background jobs do not (pre-restart job ids report |
Full contract: docs/ARCHITECTURE.md.
ChatGPT tunnel and Codex examples
Secure MCP Tunnel: scripts/tunnel.sh supports --workspace <name>=<path> (repeatable); the script regenerates the profile automatically when the configuration changes (reusing the stored tunnel_id):
scripts/tunnel.sh --shell \
--root /path/to/project \
--workspace api=/path/to/other-project
# or drive everything from a config file
scripts/tunnel.sh --config /path/to/workspace-mcp.config.jsonIf --root is omitted, the first --workspace becomes the primary. The script validates that the --config file exists before generating the tunnel profile. The profile's mcp-command is passed straight to the server, so you can also extend it by hand:
# ~/.config/tunnel-client/workspace-mcp.yaml
mcp-command: "node /path/to/workspace-mcp/dist/index.js --root /path/to/project --workspace api=/path/to/other-project"~/.codex/config.toml (shared by the ChatGPT desktop app, Codex CLI and IDE extension):
[mcp_servers.workspace-mcp]
command = "node"
args = [
"/path/to/workspace-mcp/dist/index.js",
"--root", "/path/to/project",
"--workspace", "api=/path/to/other-project",
"--shell"
]Security model
Trust model. The server runs as a normal child process with your OS user's permissions; it is not a sandbox. --root is the intended boundary: everything inside it is fair game (including deletion of content through overwrites and edits), everything outside is not reachable through these tools. Run it with an account that has no more filesystem access than you want the agent to have. A malicious or confused model with write access to a workspace can still destroy that workspace - version control and backups remain your safety net.
Containment. Every path argument goes through one implementation:
Absolute paths outside the root are rejected; relative paths resolve against the root.
Both the root and the target are canonicalized with
fs.realpath. For a target that does not exist yet (a new file), the nearest existing ancestor is realpath-ed and the remaining segments are appended - so a symlinked ancestor that escapes is caught.The final real path must equal the root or start with
root + path.sep, otherwise the tool fails withpath outside workspace root: <input>.
This blocks ../../etc/passwd, absolute paths such as /etc/passwd, and symlinks inside the workspace that point outside it (for reads and writes).
Other deliberate restrictions:
No command execution unless you opt in. With no
--shell/--shell-anyflag, no shell env vars and no configshell.mode,run_commandis not registered andtools/listexposes exactly nineteen tools: the six filesystem tools plusworkspace_list,work_log,remember,recall,git_status,git_diffand the seven change tools. When enabled, read the dedicated subsection below. A configshell.denylist is enforced in every mode.Binary files (NUL byte within the first 8 KiB) cannot be read or searched;
list_filesomits them..git,node_modules,.cacheand.workspace-mcpdirectories are skipped bygrepandlist_files.Symbolic links are never followed during directory traversal (prevents loops and escape).
Tool errors are sanitized: one short sentence, no stack traces, no raw filesystem errors. Full details are logged to stderr only.
HTTP mode: the bearer token is compared in constant time, and requests without it get
401. The token never appears in logs.Known limitations: path checks and the subsequent file operation are not a single atomic operation (TOCTOU);
patchwrites files one by one after validating all edits, so a disk error mid-write can leave some files updated; there is no rate limiting, audit log or per-tool allowlist; the HTTP transport trusts the network beyond the token (put a TLS-terminating reverse proxy in front for anything non-local).
Command execution (opt-in)
run_command exists so an agent can run tests, linters, builds and commands such as git status in the workspace. Be honest about what it is: an allowlist is a guardrail against casual or accidental execution, NOT a sandbox.
Off by default. Without
--shell,--shell-any, theWORKSPACE_MCP_SHELLenv vars or a configshell.mode, the tool is not registered at all.No shell parsing. The command is an argv array executed with
spawn(..., { shell: false }). Pipes (|),&&, redirection (>),$VARexpansion and globs are passed as literal arguments and are never interpreted - that is the whole point.The allowlist is not containment. In allowlist mode the executable name (
path.basename(command[0])) must be in the allowlist (pnpm,npm,npx,nodeby default; extend with--shell-allow,WORKSPACE_MCP_SHELL_ALLOWor configshell.allow). Butnode -e,npxand package scripts can execute arbitrary code, so every allowlisted entry already implies arbitrary-code execution.--shell-anyskips the check entirely and prints a loud warning to stderr.Deny always wins. A config
shell.deny(orWORKSPACE_MCP_SHELL_DENY) list is checked before the allowlist in both modes, and no flag can remove it: the command fails withcommand denied by configuration: <name>.Same OS permissions. The child runs with your OS user's permissions.
cwdis confined to the workspace root, but the process itself can reach anything your user can.Environment scrubbing.
CONTROL_PLANE_API_KEY,OPENAI_API_KEY,OPENAI_ADMIN_KEYandMCP_TOKENare removed from the child environment;NO_COLOR=1andFORCE_COLOR=0are set.Timeouts kill the process group. Default 120 s (config
shell.timeoutMschanges the default), max 600 s. On timeout the whole group receivesSIGTERM, thenSIGKILLafter a 3 s grace period.Output is bounded. stdout and stderr are merged (best effort, arrival order), ANSI escape codes are stripped, and above 256 KiB only the first 32 KiB and the last 32 KiB are kept - the tail is where test failures print.
ChatGPT asks for confirmation per call. The tool is annotated
readOnlyHint: false,destructiveHint: true,openWorldHint: true, so ChatGPT requests approval for every invocation; it cannot be made read-only because it is not.
How to enable:
Local / ChatGPT desktop (Work) / Codex config (
~/.codex/config.toml): append--shell(allowlist) or--shell-any(unrestricted) to the server args, e.g.args = ["/path/to/workspace-mcp/dist/index.js", "--root", "/path/to/project", "--shell"].Config file: put
{ "shell": { "mode": "allowlist" } }inworkspace-mcp.config.json(or the global path) and start the server with no shell flags. See Configuration file.ChatGPT chat through Secure MCP Tunnel:
scripts/tunnel.sh --root /path --shellor--shell-any, or point it at a config file withscripts/tunnel.sh --config /path/to/workspace-mcp.config.json. The script exportsWORKSPACE_MCP_SHELL=1/WORKSPACE_MCP_SHELL_MODE=anybeforeexec tunnel-client run, and the daemon child inherits them.
Long-running commands (jobs)
run_command is synchronous: the client waits for the result. Test suites with testcontainers, docker pulls or server boots can outlive that wait - ChatGPT closes the call on timeout, the result never reaches the conversation, and the work done so far is unreachable even if the OS process is still running. start_job exists for exactly that case.
The workflow:
start_jobwith the same argv array,cwdand allowlist rules asrun_command, plus an optionalnamelabel. It returns in milliseconds with ajobId,pid,startedAtand the log file path - it never waits for output.Poll
job_statuswith thejobId. It is read-only (readOnlyHint: true), so ChatGPT does not ask for confirmation and polling is cheap. It reportsrunning/exited/killed/timed-out/failed-to-start, the exit code, duration, log size and the lasttailBytesof output (ANSI-stripped; default 8 KiB, cap 256 KiB).Call
job_killif the job must stop.SIGTERMgoes to the whole process group,SIGKILLfollows after 3 seconds. Killing an already finished job is not an error.
Details worth knowing:
Jobs survive client disconnects. The process is spawned detached and the registry is process-global, so a timed-out call, a dropped transport or a fresh server instance in stateless HTTP mode can still read the job with
job_status. This is the point of the feature.Logs live outside the workspace, at
$TMPDIR/workspace-mcp-jobs/<jobId>.log(normally/tmp/workspace-mcp-jobs/), or under$WORKSPACE_MCP_JOB_DIRwhen that variable is set. stdout and stderr append there, so they never show up inlist_filesorgrep.The log is capped at 64 MiB per job. Past the cap output is discarded;
job_statusthen showslog capped at 64 MiB.maxRuntimeMsbounds the job: default 30 minutes, minimum 1 second, cap 2 hours. On expiry the process group is killed and the status becomestimed-out.Restarting the daemon kills running jobs. Jobs live in the server process;
SIGINT/SIGTERM(or a stdio stdin close) terminates every running job's process group before exiting, so no orphans are left behind. There is no durable queue.Same guardrails as
run_command. Allowlist mode applies before spawning (validation failures are synchronous errors and create no job), the environment is scrubbed,cwdis confined to the workspace root, and there is no shell. The child still runs with your OS user's permissions.
Memory and tracking
The server keeps a small, workspace-local memory so a new chat can recover context without the user re-explaining anything. Every workspace has its own state, and everything lives under the selected workspace's <workspace-root>/.workspace-mcp/:
.workspace-mcp/
.gitignore # contains "*", so the directory stays invisible to git
journal.jsonl # automatic activity journal (mutating operations)
journal.1.jsonl # rotated previous journal, created when the size limit is exceeded
notes.jsonl # deliberate notes saved with remember
notes.1.jsonl # rotated previous notes
state.json # { "activeChange": "<id>" | null }
changes/
<id>.json # change record: title, goal, constraints, tasks
<id>/ # stage documents written on demand
proposal.md
spec.md
design.md
notes.mdThe directory is created lazily on the first write, contains its own .gitignore with * (the repository's own .gitignore is never touched), and is part of the traversal ignore list, so grep and list_files never see it.
What is journaled automatically
Every mutating tool appends one JSON line ({ ts, tool, paths?, detail?, result? }) after it completes, whether it succeeded or failed:
Tool |
|
|
|
|
|
|
|
|
|
|
|
| the joined argv |
|
| the joined argv |
|
| the job id | final status / |
What is NOT journaled: every read-only tool (read_file, grep, list_files, work_log, recall, git_status, git_diff) and job_status. Journaling is best-effort: a state write failure is logged to stderr and never changes the tool's own result. Appends are serialized per file and written with fs.appendFile, which is atomic for small lines, so concurrent tools cannot interleave.
Session-start and session-end convention
At the start of a session, call work_log (what happened recently) and recall (notes saved deliberately) to recover context. After finishing a chunk of work, call remember with what changed and what should happen next — for example:
{
"text": "Refactored auth middleware; next: add refresh-token rotation",
"tags": ["auth", "todo"]
}The server instructions sent to MCP clients carry this convention, so a cooperating model follows it without user prompting.
work_logreturns lines like2026-09-18T07:50:12.000Z edit_file src/x.ts — 2 replacements [ok], newest first, with optionalsince(ISO 8601),path(substring on any recorded path) andlimit(default 50, cap 500) filters. An empty result isno activity recorded yet.recallreturns lines like2026-09-18 [#auth] Refactored auth middleware..., newest first, filterable byquery(case-insensitive substring on the text) andtag(case-insensitive exact). No matches reportsno notes match.
Rotation and size bounds
Both streams rotate at WORKSPACE_MCP_JOURNAL_MAX_BYTES (default 5 MiB): when the current file exceeds the limit it is renamed to <name>.1.jsonl (replacing any older .1) and a fresh file is started. Reads are bounded too: at most the last 1 MiB of the current file, then the last 1 MiB of the rotated file when more entries are needed; malformed lines are skipped. detail and result are truncated to 300 characters.
Read-only git tools
git_status and git_diff are always registered — they do not need --shell. They spawn git argv-style (shell: false) with LC_ALL=C and a scrubbed environment, are annotated readOnlyHint: true, and only read the repository (nothing is fetched or written). git_status runs git status --porcelain=v1 -b with a 10 s timeout; git_diff runs git diff with a 30 s timeout, optional --cached/--stat, and a workspace-relative path resolved through the containment check and passed after --. git_diff output is capped at 64 KiB (first 32 KiB + last 32 KiB).
Changes and tasks (SDD-lite)
A change is the unit of work. It is a JSON record at .workspace-mcp/changes/<id>.json plus a sibling directory .workspace-mcp/changes/<id>/ holding stage documents written on demand (proposal.md, spec.md, design.md, notes.md). The record shape is:
{
"id": "my-change",
"title": "My change",
"goal": "optional outcome statement",
"constraints": ["no new runtime dependencies"],
"tasks": [
{ "id": "T1", "text": "wire the schema", "status": "pending", "notes": [], "createdAt": "...", "updatedAt": "..." }
],
"createdAt": "...",
"updatedAt": "..."
}.workspace-mcp/state.json stores { "activeChange": "<id>" | null }. Change JSON and state.json are written atomically (<file>.tmp + rename), so readers never observe a partial file and no .tmp remains after a successful write. Mutating change tools (change_create, change_activate, change_doc, task_add, task_update, constraint_add) are additionally serialized by an in-process mutex, so parallel tool calls from one client cannot interleave a read-modify-write and lose updates.
Workflow: change_create (creates the record and documents directory, becomes active) → change_doc for the proposal/spec/design documents, in any order and on demand → task_add to break the work down → task_update to move tasks (pending → in_progress → done, or blocked) with optional notes → constraint_add for rules the work must respect.
Re-orient in one call: change_status is read-only, needs no confirmation and never writes state. Without arguments it renders the active change in full; with all: true (or when no change is active) it lists every change newest-first with done/total task counts and an (active) marker. The only read-only change tool is change_status; all other change tools are marked readOnlyHint: false because they write state under .workspace-mcp/.
While a change is active, every journal entry written by a mutating operation is tagged with its id, and work_log accepts a change filter to scope the log to one change. The full view ends with a derived suggested next action, in priority order:
Situation | Suggestion |
no tasks and no proposal | write the proposal with |
all tasks done | run the tests and save a summary with |
any task | unblock |
any task | continue |
any task | start |
no tasks (but a proposal exists) | break the work into tasks with |
The full view also shows each stage document present or missing with its byte size, all tasks grouped by status as T1 [pending] text, every constraint, and the last 10 journal entries tagged with the change.
Limits
Limit | Value |
| 2000 (hard cap; |
| ~1 MiB |
| 2000, with |
File size that can be read or edited | 16 MiB |
| default 100, cap 1000 |
| first 1 MiB |
| default 500, cap 5000 |
| default 6, cap 12 |
Binary detection window | first 8 KiB |
Ignored directories |
|
| default 120000 ms (config |
| 256 KiB before collapsing to first 32 KiB + last 32 KiB |
| 3 s between |
| default 1800000 ms (config |
| 64 MiB hard cap, then output is discarded and flagged |
| default 8192 bytes, cap 262144 bytes |
| 20 most recent jobs |
job kill grace | 3 s between |
State rotation |
|
State read bound | last 1 MiB of the current file, then last 1 MiB of |
| default 50, cap 500 |
| default 20, cap 100 |
| max 20 tags, 50 characters each |
Journal | truncated to 300 characters |
| 10 s |
| 30 s |
| 64 KiB (first 32 KiB + last 32 KiB) |
Development
pnpm build # tsc -> dist/
pnpm typecheck # strict typecheck of src and test
pnpm test # vitest (unit + end-to-end over InMemoryTransport)
pnpm dev # tsc --watchThe test suite uses a real temporary workspace (fs.mkdtemp) and a real MCP Client over the SDK's InMemoryTransport; nothing about the filesystem is mocked. Coverage includes the handshake and tool listing, read/write/edit/patch semantics, all-or-nothing patching, path traversal and symlink escapes, grep include/ignore rules, listing depth and patterns, the glob matcher, opt-in command execution (registration on/off, allowlist rejection and extension, unrestricted mode, non-zero exits, timeouts, cwd confinement, env scrubbing, head+tail truncation and ANSI stripping), background jobs (immediate return, survival across client disconnects, allowlist/cwd rejection without job creation, tailBytes, job_kill with a dead-pid check, maxRuntimeMs, env scrubbing, ANSI stripping and shutdown hygiene), the activity journal and notes (instrumentation for every mutating tool, error entries, filters, persistence across server instances, lazy state creation, self-ignoring git directory, size rotation), the read-only git tools (porcelain status, staged/unstaged/stat/filtered diffs, non-repository and missing-git errors) and change tracking (slug ids and dedupe, atomic records, activation, document replace/append, sequential task ids, all-or-nothing task updates with notes, constraints, the derived suggestions across the lifecycle, journal tagging and the change filter, cross-instance persistence, registration counts and no leftover .tmp files), plus multi-workspace support (flag parsing, named roots, default resolution, per-workspace isolation and confinement, workspace_list, and per-workspace git/run_command).
License
Available Tools
19 toolschange_activateActivate changeA
Make an existing change the active one. While a change is active, every journal entry written by mutating operations is tagged with its id, and the change tools default to it. Returns a short summary of the change.
Inputs: changeId (required), workspace.
change_createCreate changeA
Create a tracked change (the unit of work) and make it the active change. A change is a JSON record plus a directory that holds its stage documents (proposal.md, spec.md, design.md, notes.md) written on demand with change_doc. Use it to track multi-step work so any future chat can re-orient with a single change_status call. The id is a kebab-case slug of the title, deduplicated with -2, -3, ... on collision. Next step: write the proposal with change_doc, then break the work into tasks with task_add.
Inputs: title (required), goal, workspace.
change_docWrite change documentA
Write one stage document of a change: proposal, spec, design or notes. By default the document is replaced; with append: true the new content is appended after a blank line. Documents live under /.workspace-mcp/changes//.md and can be written in any order, on demand. Returns the workspace-relative path and which stage documents exist.
Inputs: stage (required), content (required), append, changeId, +1 more.
change_statusChange statusARead-only
Read-only orientation call: the single way to re-orient on tracked work at the start of any chat. Without arguments it renders the active change in full: title, goal, stage documents present or missing, tasks grouped by status, constraints, the last ten journal entries tagged with the change, and a derived suggested next action. With all: true (or with no active change) it lists every change newest-first with done/total task counts. Never writes state and is never journaled.
Inputs: all, changeId, workspace.
constraint_addAdd constraintA
Append one constraint to a change: a rule, limit or requirement that the work must respect (for example 'no new runtime dependencies'). Constraints are shown by change_status so later chats do not have to re-ask.
Inputs: text (required), changeId, workspace.
edit_fileEdit fileADestructive
Replace an exact string in an existing text file. The oldString must match the file content exactly, including whitespace and indentation. If oldString appears more than once, either add more surrounding context to make it unique or set replaceAll=true. Read the file first with read_file. The change is written to disk immediately and is not reversible. For several files or several changes at once, prefer patch so all edits succeed or none are applied.
Inputs: path (required), newString (required), oldString (required), workspace, +1 more.
git_diffGit diffARead-only
Read-only git diff of the workspace: runs 'git diff' without a shell (LC_ALL=C, 30 s timeout) and returns the patch text. Use staged=true for the index (--cached), stat=true for a diffstat (--stat), and path to limit the diff to one workspace-relative file (passed after '--'). Reports '(no changes)' when the diff is empty. Output longer than 64 KiB keeps the first 32 KiB and the last 32 KiB. No --shell flag is needed for this tool.
Inputs: path, stat, staged, workspace.
git_statusGit statusARead-only
Read-only git status of the workspace: runs 'git status --porcelain=v1 -b' without a shell (LC_ALL=C, 10 s timeout) and returns a 'branch: ...' header followed by the porcelain lines exactly as git prints them. A clean tree reports 'working tree clean'. A directory that is not a git repository or a missing git binary is reported as a clear error. No --shell flag is needed for this tool.
Inputs: workspace.
grepSearch file contentsARead-only
Search file contents in the workspace with a JavaScript regular expression and return matches as 'relative/path:LINE: '. Use this to find where a symbol, string or pattern appears. Narrow the search with path and include. Skips binary files and the .git, node_modules and .cache directories. Do not use it to list files (use list_files) or to read a known file (use read_file).
Inputs: pattern (required), path, include, workspace, +2 more.
list_filesList filesARead-only
List files and directories inside the workspace, sorted by workspace-relative path. Directories are marked with a trailing '/'. Use this to discover what exists before reading or editing, optionally filtered with a glob pattern. Skips the .git, node_modules and .cache directories and does not follow symbolic links. Do not use it to read content (use read_file) or to search text (use grep).
Inputs: path, limit, pattern, maxDepth, +1 more.
patchPatch filesADestructive
Apply several exact-string edits across one or more files in a single all-or-nothing operation. Every edit is validated against the current file contents first; if any edit fails, NO file is modified and the failing edit index is reported. Use this instead of several edit_file calls when changes belong together. Read the affected files first with read_file. Changes are written to disk immediately when all edits are valid.
Inputs: edits (required), workspace.
read_fileRead fileARead-only
Read a UTF-8 text file from the workspace and return its content with 1-based line numbers in the form 'N: '. Use this before editing a file, or to inspect specific line ranges with offset/limit. Do not use it for binary files (they are rejected), to search file contents (use grep), or to discover files (use list_files).
Inputs: path (required), limit, offset, workspace.
recallRecall notesARead-only
Read the persistent notes saved with remember for this workspace, newest first. Call it at the start of a session together with work_log to recover context from previous chats. Filter by free-text query (case-insensitive substring) and/or tag. This tool is read-only; use work_log for the automatic activity journal instead.
Inputs: tag, limit, query, workspace.
rememberRemember noteA
Save a short persistent note for this workspace so any future chat can recover it with recall. Use it after finishing a chunk of work: record what changed, what should happen next, or a decision that must survive the conversation. Notes are append-only JSONL stored under /.workspace-mcp/ and are never edited or deleted by this tool. Keep each note short and self-contained; use tags for later filtering.
Inputs: text (required), tags, workspace.
task_addAdd taskA
Append one task to a change. Task ids are sequential (T1, T2, ...). The task starts as pending unless another status is given. Use task_update to move a task between statuses.
Inputs: text (required), status, changeId, workspace.
task_updateUpdate tasksA
Update the status of one or more tasks in a single all-or-nothing write: every taskId is validated before anything is stored, so one unknown id leaves the change untouched and the error lists the bad entries. An optional note is appended to the task's notes. One aggregate journal entry is written.
Inputs: updates (required), changeId, workspace.
work_logWork logARead-only
Read the automatic activity journal of this workspace: a newest-first list of the mutating operations this server performed (write_file, edit_file, patch, run_command, start_job, job_kill) plus the change-tracking operations (change_create, change_activate, change_doc, task_add, task_update, constraint_add), each with timestamp, paths, a short detail and the outcome. Entries made while a change was active carry a change tag, so the log can be scoped to one change. Call it at the start of a session to recover what happened in previous chats. Read-only operations (read_file, grep, list_files, work_log itself, recall, git tools, change_status) are never journaled. Filter with since, path and change; use recall to read the deliberate notes saved with remember.
Inputs: path, limit, since, change, +1 more.
workspace_listList workspacesARead-only
Read-only list of the named project workspaces served by this process: name, absolute root path, which one is primary, whether it already has workspace state under .workspace-mcp/, and the id of its active change when state.json exists. Every path or state tool accepts an optional workspace argument (defaults to the primary workspace), so call this first to discover the available names.
Inputs: no named parameters.
write_fileWrite fileADestructive
Create a file (parent directories are created automatically) or overwrite an existing file with exactly the given content. Use this for new files or full rewrites. Prefer edit_file or patch for targeted changes to existing files, because this tool replaces the whole file and is not reversible. The file is written to disk immediately.
Inputs: path (required), content (required), workspace.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 19 tools
Every tool targets a distinct operation: file read/write/edit/patch/list/grep are clearly separated, work_log is distinguished from remember/recall, and each change/task tool has a unique role. The closest pair is edit_file vs patch, but their single-edit vs atomic-multi-edit scopes are explicitly documented.
Most file tools use verb_noun style (read_file, write_file, edit_file, list_files), while change and task tools reverse it (change_create, task_add, constraint_add), and standalone names appear (patch, grep, git_status). The naming is readable and grouped by domain, but the mixed verb placement makes the pattern less predictable.
19 tools is on the upper end, but the server spans four distinct subdomains—file editing, persistent memory, git inspection, and change/task tracking—and each tool has a separate responsibility. The count feels slightly heavy rather than bloated, with no true redundancy.
The file surface covers list/read/write/edit/patch/grep but lacks a delete or rename operation, leaving cleanup workflows with a dead end. Change tracking supports create/status/document/task updates but has no way to remove a change or constraint. These are notable, work-around-able gaps rather than a total lack of coverage.
Related MCP Connectors
Read and write shared BitsWeave context, projects, tasks, and work sessions through MCP.
One MCP server for all your MCP servers: code mode, per-tool permissions, approvals and audit.
Project management shared by people and AI agents, with persistent project state through MCP.
A MCP server built for developers enabling Git based project management with project and personal…
Related MCP Servers
FlicenseNot gradedqualityBmaintenanceProvides coding agents with a durable, revision-aware project workspace for semantic context, governed source changes, verification, task checkpoints, and observability through an MCP interface.1-- FlicenseNot gradedqualityBmaintenanceEnables MCP clients to manage files in an isolated workspace and perform lightweight Git operations through a protected Streamable HTTP endpoint, including listing, reading, writing, searching, replacing, and deleting files plus checking status and diffs.1-
- AlicenseCqualityBmaintenanceEnables MCP-compatible agents to operate a versioned shared workspace system through standard tools, including project initialization, file operations, branching, merging, publishing, checkpoints, deduplicated storage, command execution, and background process management over stdio or Streamable HTTP.4123 npmMIT
- FlicenseAqualityBmaintenanceEnables MCP clients to manage a workspace through file reading, writing, editing, searching, Bash/Python execution, and job control, with optional desktop GUI and Cloudflare Tunnel access.124-