Universal Dev Workspace v9.0.0

Status: Marketplace Certified – Claude Code Plugin + Anthropic Best Practices ✅

Focused MCP server for local development workflows with 29 core DevOps tools.

---

Quick Links

- 🚀 5-Minute Quick Start - Get up and running fast
- 📚 Tools Reference - 6 unified tools (default) + legacy (optional)
- 🔧 Troubleshooting Guide - Error solutions and diagnostics
- 🤝 Contributing - How to contribute to the project
- 📝 Changelog - Version history and release notes

---

> 🚀 v9.0.0: Focused DevOps Toolset
>
> Breaking Changes: Removed GitHub module (3 tools) and Browser module (13 tools). Removed all unified tools.
> v9.0.0 focuses on core local development workflows with 29 granular tools.
>
> Migration from v8.x: Use individual tool names (read_file, write_file) instead of unified tools (use_files). No GITHUB_TOKEN needed.
>
> 29 Core Tools: Files (10), Processes (7), Git (10), Search (2)
>
> Configuration Example:
> ``json
> {
> "mcpServers": {
> "universal-dev-workspace": {
> "command": "npx",
> "args": ["-y", "@anthonybir/universal-dev-workspace"],
> "env": {
> "WORKSPACE_PATH": "${HOME}/Documents",
> "GITHUB_TOKEN": "ghp_your_token_here"
> }
> }
> }
> }
> `
>
> Legacy Tools: Set UDW_UNIFIED_ONLY=0 to expose 33 granular tools (increases token usage).
>
> Tip: Use MCP resources for on-demand action help: udw://quickref and udw://quickref/use_*.

---

What is Universal Dev Workspace?

A focused MCP (Model Context Protocol) server that provides 29 core DevOps tools for local development workflows with AI assistants like Claude Code and Claude Desktop.

$3

- 🗂️ 10 File Tools: Complete file management with workspace path validation (read_file, write_file, edit_block, list_directory, directory_tree, create_directory, delete_file, copy_file, move_file, get_file_info)
- 🌿 10 Git Tools: Full version control workflow (git_status, git_diff, git_add, git_commit, git_log, git_branch, git_push, git_pull, git_stash, git_clone)
- 💻 7 Process Tools: REPL-aware interactive sessions (execute_command, start_process, interact_with_process, read_process_output, force_terminate, list_sessions, start_dev_server)
- 🔍 2 Search Tools: Fast file and code search (search_files, search_code)

$3

- Workspace Containment: Filesystem operations restricted to configured workspace with detailed diagnostics
- Signal Passthrough: Process termination with SIGTERM/SIGINT/SIGKILL support
- TypeScript Strict Mode: Full type safety with noImplicitAny and strictNullChecks
- Test Coverage: Comprehensive smoke tests for critical functionality
- Startup Diagnostics: Clear workspace path logging for troubleshooting

$3

- ✅ TypeScript Strict Mode: noImplicitAny, strictNullChecks, ESLint clean
- ✅ Marketplace Certified: Anthropic best practices compliant
- ✅ 29 Focused Tools: Core DevOps capabilities only

---

Installation

Universal Dev Workspace supports 4 installation methods to fit your workflow:

$3

One-click installation for Claude Desktop users:

1. Download universal-dev-workspace-9.0.0.mcpb
2. Double-click the file
3. Claude Desktop installs and configures automatically

→ Detailed .mcpb Setup Guide

---

$3

Plugin marketplace installation for Claude Code users:

`bash
/plugin install universal-dev-workspace
`

Includes 4 slash commands, 4 agents, 1 skill, and auto-configured MCP server.

→ Detailed Plugin Setup Guide

---

$3

Universal installation for any MCP client:

`bash


Run directly (no install needed)

npx @anthonybir/universal-dev-workspace

Or install globally

npm install -g @anthonybir/universal-dev-workspace
`

Manual Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json):

`json
{
"mcpServers": {
"universal-dev-workspace": {
"command": "npx",
"args": ["-y", "@anthonybir/universal-dev-workspace"],
"env": {
"WORKSPACE_PATH": "${HOME}/Documents"
}
}
}
}
`

→ Detailed npm Setup Guide

---

$3

Build from source for development or customization:

`bash
git clone https://github.com/anthonybir/universal-dev-workspace.git
cd universal-dev-workspace
npm install
npm run build
npm run start:server
`

→ Developer Setup Guide

---

Example Prompts

Get started with these proven workflows for common development tasks:

$3

`
Analyze the authentication module in src/core/auth.ts:
1. Read the file and explain the OAuth 2.1 flow
2. Search for all files that import from auth.ts
3. Check if there are any TODO comments
4. Suggest improvements for error handling
`

Demonstrates: File reading, code search, cross-file analysis, architectural review

---

$3

`
I'm getting a TypeError in my Next.js app. Help me debug:
1. Start a Node REPL process
2. Import the problematic module
3. Test the failing function with sample data
4. Identify the root cause and suggest a fix
`

Demonstrates: Process management, REPL interaction, live code execution, debugging workflow

---

$3

`
Implement a new user profile page:
1. Create a new git branch called feature/user-profile
2. Generate the component file at src/components/UserProfile.tsx
3. Write unit tests in src/components/UserProfile.test.tsx
4. Check git status and stage all changes
5. Commit with message "feat: add user profile component"
`

Demonstrates: Git branching, file creation, test generation, version control workflow

---


---

Tool Catalog

Universal Dev Workspace provides 29 tools across 4 categories:

| Category | Tools | Description |
|----------|-------|-------------|
| Files (10) | read_file, write_file, edit_block, list_directory, directory_tree, create_directory, delete_file, copy_file, move_file, get_file_info | Complete file management with workspace containment |
| Git (10) | git_status, git_diff, git_add, git_commit, git_log, git_branch, git_push, git_pull, git_stash, git_clone | Full version control workflow |
| Processes (7) | execute_command, start_process, interact_with_process, read_process_output, force_terminate, list_sessions, start_dev_server | REPL-aware interactive sessions |
| Search (2) | search_files, search_code | Fast file and code search with regex |

→ Complete Tool Reference

---

Configuration

$3

The WORKSPACE_PATH environment variable defines the root directory for all filesystem operations:

`bash


Example configurations


WORKSPACE_PATH="${HOME}" # Access entire home directory
WORKSPACE_PATH="${HOME}/Documents" # Restrict to Documents folder
WORKSPACE_PATH="/Users/username/Projects" # Specific project directory
`

Important:
- Paths are resolved using realpath for security (follows symlinks, normalizes case)
- All file operations must stay within the workspace
- Path validation provides detailed diagnostics on rejection

$3

Server logs workspace configuration at startup:

`
🚀 Universal Dev Workspace v9.0.0 starting...
Workspace: /Users/username/Documents
Source: WORKSPACE_PATH env var
`

$3

When a path is rejected (outside workspace), detailed diagnostics are provided:

`
Path outside workspace not allowed
Input: ../../../etc/passwd
Workspace: /Users/username/Documents
Target (canonical): /etc/passwd
Relative path: ../../../etc
Reason: Path starts with '..'
`

Common Issues:
- macOS: Documents Desktop folders may require different workspace roots
- Symlinks: Resolved automatically, but final path must be within workspace
- Case sensitivity: Handled automatically on macOS (case-insensitive)

$3

IMPORTANT: use_files operates on your local host filesystem, NOT in a container:

- Direct host access: Reads and writes files on your machine's filesystem
- WORKSPACE_PATH defines root: All operations are relative to this directory
- No containerization: Files are accessed directly via Node.js fs module

Example:
`bash
WORKSPACE_PATH=/Users/username/Documents
`
This allows use_files to read/write ANY file under /Users/username/Documents on your HOST machine.

Common Misconception: Some users think the workspace is containerized or sandboxed. It's not - it's your actual local filesystem with path validation for security.

$3

- No environment variables required beyond WORKSPACE_PATH
- All 29 tools are always available (no feature flags)

---

Requirements

- Node.js: 20.0.0 or higher
- npm: 9.0.0 or higher
- Operating System: macOS, Linux, or Windows (WSL2 recommended)
- Git: For git tools (optional)

→ Prerequisites Details

---

Development

`bash


Install dependencies

npm install

Build TypeScript

npm run build

Run tests

npm test

Watch mode

npm run test:watch

Coverage report

npm run test:coverage

Type checking

npm run typecheck

Linting

npm run lint
npm run lint:fix
`

→ Contributing Guide

---

Project Structure

`
universal-dev-workspace/
├── src/
│ ├── server.ts # MCP entry point (~300 lines)
│ ├── modules/ # Tool modules (~1800 lines)
│ │ ├── files/ # 10 file tools + workspace validation
│ │ ├── git/ # 10 git tools
│ │ ├── processes/ # 7 process tools + signal control
│ │ └── search/ # 2 search tools
│ └── types.ts # Type definitions
├── tests/ # Smoke tests for v8.0.0
│ └── unit/
│ └── v8-smoke.test.ts # 8 critical tests
├── docs/ # Documentation
│ ├── user/ # User-facing documentation
│ │ ├── QUICKSTART.md # 5-minute getting started
│ │ ├── TROUBLESHOOTING.md # Error solutions
│ │ └── CONTRIBUTING.md # Developer guide
│ ├── development/ # Development documentation
│ │ └── CHANGELOG.md # Version history
│ ├── api/ # API documentation
│ ├── guides/ # Implementation guides
│ └── architecture/ # Architecture decisions
├── plugins/ # Claude Code plugin
│ └── universal-dev-workspace/
│ ├── agents/ # 4 specialized agents
│ ├── commands/ # 4 slash commands
│ └── skills/ # 1 skill definition
``

---

Getting Help

$3

- Quick Start: Installation and setup in 5 minutes
- Troubleshooting: Common errors and solutions
- Tools Reference: Complete tool catalog
- FAQ: Frequently asked questions
- Changelog: Version history

$3

- Issues: Report bugs at https://github.com/anthonybir/universal-dev-workspace/issues
- Discussions: Ask questions in GitHub Discussions
- Security: Email security@bir.com.py (do not open public issues)

---

License

MIT © Anthony Bir

---

Acknowledgments

- Anthropic: For Claude and the MCP specification
- Community: For bug reports, feature requests, and contributions

---

Version: 9.0.0

What's New in 9.0.0

$3

Breaking Changes: Removed 16 tools to focus on core local development workflows.

Removed:
- GitHub module (3 tools): github_file_operation, search_github_code, get_github_commits
- Browser module (13 tools): All Chrome DevTools Protocol automation tools
- Unified tools (6): use_files, use_process, use_git, use_search, use_github, use_browser

Why:
- GitHub operations can be done via git CLI + push/pull
- Browser automation is specialized - use dedicated browser MCP if needed
- Direct tool names (read_file, write_file) are clearer than unified tools (use_files with actions)
- Smaller package size, faster loading, less token usage

Kept (29 tools):
- Files (10): read_file, write_file, edit_block, list_directory, directory_tree, create_directory, delete_file, copy_file, move_file, get_file_info
- Processes (7): execute_command, start_process, interact_with_process, read_process_output, force_terminate, list_sessions, start_dev_server
- Git (10): git_status, git_diff, git_add, git_commit, git_log, git_branch, git_push, git_pull, git_stash, git_clone
- Search (2): search_files, search_code

Package Size Reduction:
- v8.1.2: 193.7KB MCPB
- v9.0.0: 115KB MCPB
- Reduction: ~79KB (~-40%)

Migration from v8.x:
- Remove GITHUB_TOKEN from environment (no longer needed)
- Use individual tool names (read_file, write_file) instead of unified tools (use_files)
- For GitHub operations: Use git commands + push/pull
- For browser automation: Install separate browser automation MCP server if needed

Node.js: 20.0.0+
MCP SDK: 0.6.0
Bundle Size: ~290KB (server.bundle.js)
Repository: https://github.com/anthonybir/universal-dev-workspace