@anthonybir/universal-dev-workspace

v9.0.3

Published

5 months ago

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

Downloads

0High
0Medium
0Low

anthonybir

mcp claude development workspace devops typescript tools automation

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:
{
  "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.

Key Features

🗂️ 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)

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
✅ 29 Focused Tools: Core DevOps capabilities only

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-9.0.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 4 slash commands, 4 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"
      }
    }
  }
}

→ 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

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

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 v9.0.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.

Configuration Notes

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

# 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

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 [email protected] (do not open public issues)

License

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

🎯 Focused DevOps Toolset

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