Workspace MCP

Workspace MCP is a generic, secure local development platform that exposes controlled developer capabilities to AI clients through the Model Context Protocol (MCP).

It is not a Merciless Janitors Studios product. MJS is one consumer and may ship an extension package—the core must work for any developer who has never heard of MJS.

Mission

Allow AI assistants to work naturally inside explicitly authorized development workspaces—with deny-by-default security, audit logging, and capability-aware adaptation to each repository.

Status

Attribute	Value
Phase	Phase 2 — M2 search + commands implemented
MCP server	M1+M2 stdio server (src/core/)
Product maturity	0.1.0
OS/capsule	Agentic Delivery OS v1.5.7
Initial authorized root	~/Documents/dev (hypothesis)

M2 Tools (Implemented)

Tool	Capability	Description
search_repo	search:repo	Search filenames or content
command_exec	command:exec	Run allowlisted commands by ID

Permission profiles: observer (read+search), maintainer (+commands). See config/examples/commands.json.

M1 Tools (Implemented)

Tool	Capability	Description
workspace_list	workspace:list	List registered workspaces in grant
fs_list	fs:list	Directory listing
fs_read	fs:read	Read UTF-8 file content
git_status	git:read	Git porcelain v2 status
git_log	git:read	Bounded one-line log
git_diff	git:read	Unstaged or staged diff
detect_report	detect:report	Capability detection report

Writes, search, commands, and extensions are M2+ — see docs/hds/product/roadmap.md.

Installation

cd ~/Documents/dev/workspace-mcp
npm install
npm run build

Configuration

Copy examples and edit paths for your machine:

mkdir -p ~/.config/workspace-mcp/grants
cp config/examples/workspaces.json ~/.config/workspace-mcp/
cp config/examples/grants/local-dev.json ~/.config/workspace-mcp/grants/
cp config/examples/commands.json ~/.config/workspace-mcp/
chmod 600 ~/.config/workspace-mcp/grants/local-dev.json

Override config directory: WORKSPACE_MCP_CONFIG_DIR

Cursor / MCP Client

Add to MCP settings (stdio):

{
  "mcpServers": {
    "workspace-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/workspace-mcp/dist/index.js"],
      "env": {
        "WORKSPACE_MCP_PRINCIPAL_ID": "local-dev"
      }
    }
  }
}

Client smoke tests are M5 — configuration above is not yet validated against all clients.

Development

npm test        # 15 tests — security + auth + tools
npm run build
npm run dev     # stdio server via tsx

Core vs Extensions

Layer	Responsibility
Core	Workspace registration, FS, Git, search, safe commands, audit, permissions, capability detection, extension host
Extensions	ADOS, hDS, MJS, Universe Engine, Docker, GitHub, Figma, PostgreSQL, Node, Python, Rust, React

The core must not depend on any extension.

Documentation Map

Topic	Location
M1 contract	.agentic-harness/contracts/m1-core-readonly-contract.md
Installation	docs/hds/operations/installation-guide.md
Tool catalog (M1)	docs/hds/operations/tool-catalog-m1.md
Extension architecture	docs/hds/architecture/extension-architecture.md
Security doctrine	docs/hds/security/security-doctrine.md
Roadmap	docs/hds/product/roadmap.md

Claim Boundaries

• Not production-ready · M1 read-only only · Client integrations unverified (M5)
• No writes/search/commands until M2/M3