Package Exports

@anthonybir/universal-dev-workspace
@anthonybir/universal-dev-workspace/dist/server.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@anthonybir/universal-dev-workspace) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

Universal Dev Workspace v8.1.0

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

Powerful yet simple MCP server for personal development workflows with 6 unified 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

🚀 v8.1.0: Simplified Architecture

Breaking Changes: Removed docker_manager tool and excluded Claude Code plugin files from MCPB bundle. v8.1.0 focuses on clarity and simplicity - 6 unified tools for personal development workflows.

Migration from v8.0.x: docker_manager tool no longer available. Use Docker CLI directly if needed.

6 Unified Tools (default): use_files, use_process, use_git, use_search, use_github, use_browser

Configuration Example:
{
  "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 powerful yet simple MCP (Model Context Protocol) server that provides 33 development capabilities via 6 unified tools for AI assistants like Claude Code and Claude Desktop.

Key Features

🗂️ 10 File Tools: Complete file management with workspace path validation and diagnostics
🌿 10 Git Tools: Full version control workflow (status, diff, commit, branch, push/pull)
🐙 3 GitHub Tools: Remote repository operations (read/write files, search code, view commits)
💻 7 Process Tools: REPL-aware interactive sessions (Python, Node.js, bash, etc.) with signal control
🔍 2 Search Tools: Fast file and code search with regex support
🌐 13 Browser Actions: Chrome DevTools Protocol integration for web automation

Security & Quality

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

Quality & Certification

✅ TypeScript Strict Mode: noImplicitAny, strictNullChecks, ESLint clean
✅ Marketplace Certified: Anthropic best practices compliant
✅ v8.0.0 Smoke Tests: All 8 tests passing

Installation

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

1. 📦 Claude Desktop (.mcpb) - Recommended

One-click installation for Claude Desktop users:

Download universal-dev-workspace-8.1.0.mcpb
Double-click the file
Claude Desktop installs and configures automatically

→ Detailed .mcpb Setup Guide

2. 🔌 Claude Code Plugin

Plugin marketplace installation for Claude Code users:

/plugin install universal-dev-workspace

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

→ Detailed Plugin Setup Guide

3. 🌐 npm Package

Universal installation for any MCP client:

# 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):

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

→ Detailed npm Setup Guide

4. 💻 Source Code (Development)

Build from source for development or customization:

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:

🔍 Codebase Analysis & Refactoring

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

🐛 Debugging with Interactive Sessions

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

🚀 Feature Implementation with Git Workflow

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

🐙 GitHub Integration

Read the latest release notes from the repository:
1. Use github_file_operation to read docs/development/CHANGELOG.md from the main branch
2. Use get_github_commits to show the last 10 commits
3. Summarize what changed in the latest release

Demonstrates: GitHub API integration, remote file access, commit history

Tool Catalog

Universal Dev Workspace provides 32 tools across 5 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
GitHub (3)	github_file_operation, search_github_code, get_github_commits	Remote repository operations via API
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

Workspace Path

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

# 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

Startup Diagnostics

Server logs workspace configuration at startup:

🚀 Universal Dev Workspace v8.1.0 starting...
   Workspace: /Users/username/Documents
   Source: WORKSPACE_PATH env var

Path Rejection Diagnostics

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)

How File Operations Work

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:

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.

Optional Configuration

# GitHub integration (optional)
GITHUB_TOKEN=ghp_your_token_here

# Legacy tools (increases token usage)
UDW_UNIFIED_ONLY=0

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)
GitHub Token: For GitHub tools (optional)

→ Prerequisites Details

Development

# 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 (~675 lines)
│   ├── modules/             # Tool modules (~2400 lines)
│   │   ├── files/           # 10 file tools + workspace validation
│   │   ├── git/             # 10 git tools
│   │   ├── github/          # 3 GitHub tools
│   │   ├── processes/       # 7 process tools + signal control
│   │   ├── search/          # 2 search tools
│   │   └── browser/         # 13 browser actions
│   └── 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/          # 5 specialized agents
│       ├── commands/        # 5 slash commands
│       └── skills/          # 1 skill definition

Getting Help

Documentation

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

Support

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

Acknowledgments

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

Version: 8.1.0

What's New in 8.1.0

🧹 Simplified Architecture

Breaking Changes:

Removed docker_manager unified tool (use Docker CLI directly if needed)
Claude Code plugin files excluded from MCPB bundle (cleaner Claude Desktop experience)

Architecture Changes:

7 unified tools → 6 unified tools
33 total capabilities → 32 total capabilities
~~2500 lines → ~2400 lines (~~100 lines removed)
Plugin files (skills, agents, commands) no longer included in MCPB package

Why This Change:

Eliminated confusion about containerization in Claude Desktop
docker_manager was not essential for core development workflows
Cleaner separation between Claude Desktop (MCP) and Claude Code (plugin) contexts
Smaller MCPB bundle size

Target: Personal development workflows with maximum clarity

Migration from v8.0.x: If you used docker_manager, use Docker CLI commands via use_process instead.

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