mcpserver-cowork

McpServer Claude Cowork Plugin

Connect Claude Cowork to McpServer for workspace-scoped TODO management, session logging, requirements tracking, and GraphRAG knowledge graph operations.

This is the Cowork-oriented sibling of mcpserver-claude-code-plugin. It keeps the same marker-trusted MCP contract and repaired fallback behavior, but it does not assume a Claude Code project launch environment.

Features

• Installs as a Claude plugin package with .claude-plugin/plugin.json.
• Prompts for a workspace_path pointing at a workspace that contains AGENTS-README-FIRST.yaml.
• Bundles an mcpserver stdio connector using mcpserver-repl --agent-stdio.
• Keeps the repaired local failsafe behavior from the Claude Code plugin: bounded REPL calls, HTTP fallback diagnostics, pending import transformation, TODO shaping, and session-log recovery support.
• Provides four skills: TODO, Session Log, Requirements, and GraphRAG.
• Provides hooks for environments that enable Cowork plugin hooks; hooks degrade to local handoff/cache files instead of dropping data when McpServer is unavailable.

Prerequisites

• McpServer running with the target workspace registered.
• The target workspace must contain a current AGENTS-README-FIRST.yaml.
• mcpserver-repl must be available on PATH for the local Cowork runtime.
• If using a remote/custom Cowork connector path instead of local stdio, the server must be reachable from Anthropic's network as described in the Cowork plugin docs.

Install In Cowork

1. Package this directory:

pwsh -NoLogo -NoProfile -File .\scripts\package-plugin.ps1

2. In Claude Desktop, open Cowork, then Customize -> Plugins.
3. Upload dist\mcpserver-cowork-plugin.zip.
4. Set workspace_path to the absolute local workspace path, for example F:\GitHub\McpServer.
5. Reload/validate before writing MCP data:
   • marker trust succeeds
   • workflow.sessionlog.queryHistory succeeds
   • workflow.todo.query succeeds
   • workflow.requirements.generateDocument with format: wiki, docType: all returns ZIP bytes

Install From A Marketplace Repository

Cowork can add a GitHub repository as a plugin marketplace. This workspace includes .claude-plugin/marketplace.json with a single mcpserver-cowork entry pointing at the repository root. If this repository is published, add it from the Cowork plugin UI and install mcpserver-cowork from that marketplace.

Cowork Contract

The Cowork variant intentionally separates two paths:

• The MCP connector path exposes mcpserver-repl --agent-stdio to Cowork as the tool transport.
• The hook/skill helper path uses the repaired shell shims for local marker bootstrap, session-log turn tracking, TODO shaping, requirements ZIP fallback, and outage handoff files.

The plugin must not bypass AGENTS-README-FIRST.yaml trust. If marker verification or health nonce verification fails, MCP writes must stop and local handoff/failsafe files must be retained for later import.

Tool Name Surfaces

This plugin's workflow.sessionlog.*, workflow.todo.*, and workflow.requirements.* names are plugin workflow/REPL method names used by the Cowork skills and helper scripts. They are distinct from native McpServer MCP tool names exposed by /mcp-transport, such as sessionlog_*, todo_*, and requirements_*, and from hosted-agent aliases such as mcp_session_*.

Do not treat the absence of literal workflow.* names from generic MCP tool discovery as proof that this plugin is unavailable. Validate the Cowork plugin connector, marker trust, and helper wrapper path instead.

Local stdio MCP - how it works

Cowork loads the MCP server entry from .mcp.json at plugin install time:

"command": "${CLAUDE_PLUGIN_ROOT}/bin/mcpserver-stdio.cmd",
"args": []

${CLAUDE_PLUGIN_ROOT} is expanded by Cowork to the plugin's installed root. The wrapper calls mcpserver-repl --agent-stdio and fails with a clear message if the tool is not on PATH.

macOS/Linux: Change command to ${CLAUDE_PLUGIN_ROOT}/bin/mcpserver-stdio.sh in .mcp.json before packaging, then rebuild the zip.

Verify that local MCP is enabled

Cowork Desktop supports local stdio MCP servers by default. Admin-managed Cowork instances may disable local MCP via policy. To check:

1. In Cowork go to Customize > Connectors (or Plugins > mcpserver-cowork).
2. If the connector shows "Local MCP disabled by policy" or does not list the mcpserver connector, contact your Cowork administrator.

Diagnose wrapper startup outside Cowork

Run the wrapper directly to see any startup error before Cowork gets involved:

# Windows - should block waiting for MCP JSON-RPC input (no immediate output = good)
$env:MCP_WORKSPACE_PATH = "F:\path\to\your\workspace"
$env:MCP_SESSION_AGENT  = "ClaudeCowork"
.\bin\mcpserver-stdio.cmd
# Ctrl-C to exit