Focused MCP server with 29 core DevOps tools for local development workflows
npm install @anthonybir/universal-dev-workspaceStatus: Marketplace Certified ā Claude Code Plugin + Anthropic Best Practices ā
Focused MCP server for local development workflows with 29 core DevOps tools.
---
- š 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"
> }
> }
> }
> }
> UDW_UNIFIED_ONLY=0
>
> Legacy Tools: Set to expose 33 granular tools (increases token usage).udw://quickref
>
> Tip: Use MCP resources for on-demand action help: and udw://quickref/use_*.
---
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.
- šļø 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)
- 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
- ā
TypeScript Strict Mode: noImplicitAny, strictNullChecks, ESLint clean
- ā
Marketplace Certified: Anthropic best practices compliant
- ā
29 Focused Tools: Core DevOps capabilities only
---
Universal Dev Workspace supports 4 installation methods to fit your workflow:
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
---
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
---
Universal installation for any MCP client:
`bashRun directly (no install needed)
npx @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"
}
}
}
}
`---
$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
`---
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 |
---
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 moduleExample:
`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)
---
Development
`bash
Install dependencies
npm installBuild TypeScript
npm run buildRun tests
npm testWatch mode
npm run test:watchCoverage report
npm run test:coverageType checking
npm run typecheckLinting
npm run lint
npm run lint:fix
`---
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
``---
- 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
- 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)
---
MIT Ā© Anthony Bir
---
- Anthropic: For Claude and the MCP specification
- Community: For bug reports, feature requests, and contributions
---
Version: 9.0.0
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