Engineering Manager MCP

An MCP (Model Context Protocol) server that provides LLMs with structured workflow guidance and "next step" instructions for development procedures. Perfect for maintaining consistent development practices across projects without having to repeatedly explain procedures to AI assistants.

This project welcomes contributions from AI/LLM agents! Pull requests from Claude, GPT, and other AI models are actively encouraged.

Guidelines for AI contributors:

Follow existing code patterns and documentation standards
Include comprehensive commit messages explaining changes
Test changes thoroughly before submitting PRs
Update documentation when adding new features

🎯 Purpose

Engineering Manager MCP solves a common problem: LLMs forget your development procedures. Instead of repeatedly reminding your AI assistant about branch naming conventions, commit message formats, PR templates, or deployment steps, let Engineering Manager MCP provide that guidance on demand.

Use Cases:

🔄 Consistent Workflows - Maintain standardized development procedures across projects
📋 Step-by-Step Guidance - LLMs can query "what's next?" at any point in the workflow
🎯 Context-Aware Suggestions - Returns relevant workflow sections based on current task
🔧 Multi-Project Support - Different procedures for different projects
📝 Template Variables - Customize procedures with project-specific values

✨ Quick Start

Installation from PyPI

# Run directly with uvx (recommended)
uvx engmanager-mcp

# Or install with pip
pip install engmanager-mcp

Configure in Claude Code

For project-specific configuration, add to your local .mcp.json in the project directory, or add to your global claude_code_config.json:

{
  "mcpServers": {
    "engmanager": {
      "command": "uvx",
      "args": ["engmanager-mcp"],
      "env": {
        "ENGMANAGER_DEFAULT_PROJECT": "myproject"
      }
    }
  }
}

Create Your First Project

Create a project configuration:

mkdir -p ~/.config/engmanager-mcp
cat > ~/.config/engmanager-mcp/myproject-config.json <<EOF
{
  "project_name": "myproject",
  "procedure_file": "myproject-workflow.md",
  "variables": {
    "REPO_OWNER": "yourname",
    "REPO_NAME": "myproject",
    "DEFAULT_BRANCH": "main"
  }
}
EOF

Create a workflow procedure:

cat > ~/.config/engmanager-mcp/myproject-workflow.md <<EOF
# My Project Workflow

## 1. Branch Creation

Create a feature branch:
\`\`\`bash
git checkout -b feature/my-feature
\`\`\`

## 2. Development

Make your changes and commit:
\`\`\`bash
git add .
git commit -m "feat: description"
\`\`\`

## 3. Push & PR

Push and create a pull request:
\`\`\`bash
git push -u origin feature/my-feature
gh pr create --title "feat: Description"
\`\`\`
EOF

Use in Claude:

You: "What's the first step in the workflow?"
Claude: [calls get_next_step tool]
Engineering Manager MCP: Returns "Step 1: Branch Creation..."

You: "What's next?"
Claude: [calls get_next_step with current_step=1]
Engineering Manager MCP: Returns "Step 2: Development..."

🔧 Available Tools

`get_next_step`

Get the next step in the workflow.

get_next_step(project="myproject", current_step=1)

Parameters:

project (optional): Project name (uses default if not specified)
current_step (optional): Current step number (defaults to 0 for first step)

`get_workflow_section`

Get a specific section from the workflow by name.

get_workflow_section(section="Error Recovery Protocols", project="myproject")

`list_workflow_steps`

Get an overview of all numbered steps.

list_workflow_steps(project="myproject")

`list_available_projects`

List all configured projects.

list_available_projects()

`get_project_info`

Get detailed information about a project's configuration.

get_project_info(project="myproject")

📚 Available Resources

`engmanager://procedures/{project}`

Get the full procedure file with variables substituted.

`engmanager://config/{project}`

Get the project configuration.

`engmanager://templates`

Get documentation about template variables.

`engmanager://projects`

List all available projects with status.

🎨 Template Variables

Procedures support template variables for customization:

## Branch Creation for {PROJECT_NAME}

Create a branch:
\`\`\`bash
git checkout -b feature/my-feature
git push -u origin feature/my-feature
\`\`\`

Your repository: {REPO_OWNER}/{REPO_NAME}
Default branch: {DEFAULT_BRANCH}

Common Variables:

{PROJECT_NAME} - Project name
{REPO_OWNER} - GitHub repository owner
{REPO_NAME} - GitHub repository name
{DEFAULT_BRANCH} - Default branch (main/master)
{ISSUE_NUMBER} - Current issue number
{BRANCH_PREFIX} - Branch prefix (feature/fix/refactor)

Define custom variables in your project's config file.

📁 Project Structure

Important: The procedures/ directory is excluded from the PyPI package. When you install via uvx engmanager-mcp, you need to create your own workflow files in one of these locations:

~/.config/engmanager-mcp/          # Recommended for user-specific workflows
├── myproject-config.json          # Project configuration
├── myproject-workflow.md          # Workflow procedure
├── another-project-config.json
└── another-project-workflow.md

Configuration file locations (searched in order):

./procedures/ (relative to current directory - for local development)
~/.config/engmanager-mcp/ (user config - recommended)
/etc/engmanager-mcp/ (system-wide)

Note: Example files (example-config.json, example-workflow.md) are only available in the GitHub repository for reference, not in the PyPI package.

⚙️ Configuration

Environment Variables

ENGMANAGER_DEFAULT_PROJECT - Default project name
ENGMANAGER_MCP_LOG_LEVEL - Logging level (DEBUG, INFO, WARNING, ERROR)
ENGMANAGER_PROCEDURES_DIR - Custom procedures directory
ENGMANAGER_MCP_TRANSPORT - Transport mode (stdio or http)

Project Configuration Format

{
  "project_name": "myproject",
  "procedure_file": "myproject-workflow.md",
  "variables": {
    "REPO_OWNER": "username",
    "REPO_NAME": "repository",
    "DEFAULT_BRANCH": "main",
    "CUSTOM_VAR": "custom_value"
  }
}

Required Fields:

project_name - Unique project identifier
procedure_file - Filename of the markdown procedure

Optional Fields:

variables - Dictionary of template variables

📖 Example Use Cases

Use Case 1: Consistent Git Workflow

Problem: Different team members follow different git workflows.

Solution: Create a standardized procedure that LLMs can reference:

## 1. Branch Creation
- Always create from main
- Use conventional naming: feature/fix/refactor
- Format: <type>/<description>-issue-<number>

## 2. Commit Messages
- Use conventional commits format
- Include issue reference
- Add "Resolves #N" for auto-close

LLMs can now query these steps and follow them consistently.

Use Case 2: Multi-Project Development

Problem: Working on multiple projects with different procedures.

Solution: Configure multiple projects:

~/.config/engmanager-mcp/
├── frontend-config.json
├── frontend-workflow.md
├── backend-config.json
└── backend-workflow.md

LLMs can switch between project contexts easily.

Use Case 3: Onboarding Documentation

Problem: New team members (including AI assistants) need workflow guidance.

Solution: Comprehensive procedure files serve as executable documentation:

## Developer Setup
1. Clone repository
2. Install dependencies
3. Configure environment
4. Run development server

## Development Workflow
[Steps...]

## Deployment Process
[Steps...]

## Error Recovery
[Procedures...]

🔨 Development Setup

Local Installation

# Clone repository
git clone https://github.com/scarr7981/engmanager-mcp.git
cd engmanager-mcp

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate  # Linux/Mac
# or
.venv\Scripts\activate     # Windows

# Install dependencies
pip install -r requirements.txt

# Install in editable mode for development
pip install -e .

# Run locally
python -m engmanager_mcp.server
# or
engmanager-mcp

Development Mode with Claude Code

For local development and testing with Claude Code, add this to your project's .mcp.json file:

{
  "mcpServers": {
    "engmanager": {
      "command": "/absolute/path/to/engmanager-mcp/.venv/bin/python",
      "args": ["-m", "engmanager_mcp.server"],
      "cwd": "/absolute/path/to/engmanager-mcp",
      "env": {
        "ENGMANAGER_DEFAULT_PROJECT": "example",
        "ENGMANAGER_MCP_LOG_LEVEL": "DEBUG"
      }
    }
  }
}

Important:

Replace /absolute/path/to/engmanager-mcp with the actual path to your cloned repository
For Windows WSL, use: /mnt/c/Users/username/path/to/engmanager-mcp/.venv/bin/python
For Windows native, use: C:\\absolute\\path\\to\\engmanager-mcp\\.venv\\Scripts\\python.exe
The .mcp.json file should be in the project root directory
This file is gitignored, so your local config won't be committed

This configuration:

Uses the virtual environment's Python interpreter directly
Runs from your local development directory
Enables DEBUG logging for troubleshooting
Sets the example project as default
Allows you to edit code and see changes immediately (restart Claude Code to reload)

Testing

Create a test project:

mkdir -p procedures
cat > procedures/test-config.json <<EOF
{
  "project_name": "test",
  "procedure_file": "example-workflow.md",
  "variables": {
    "REPO_OWNER": "testuser",
    "REPO_NAME": "testrepo",
    "DEFAULT_BRANCH": "main"
  }
}
EOF

# Copy example workflow
cp procedures/example-workflow.md procedures/test-workflow.md

# Test with MCP inspector or Claude Code

📦 Publishing to PyPI

Build Package

# Install build tools
pip install build twine

# Build package
python -m build

# Check distribution
twine check dist/*

Upload to PyPI

# Upload to Test PyPI first
twine upload --repository testpypi dist/*

# Test installation
pip install --index-url https://test.pypi.org/simple/ engmanager-mcp

# Upload to PyPI
twine upload dist/*

Using GitHub Actions

This project can be configured with GitHub Actions for automatic PyPI publishing on tagged releases. See cargoshipper-mcp for reference.

🤝 Contributing

This project is inspired by the EXAMPLE_PROCEDURE.md workflow for Trowel.io and follows similar patterns.

Contribution Guidelines:

Follow existing code patterns
Add comprehensive docstrings
Update README for new features
Test with real procedures
Include example configurations

📄 License

MIT License - See LICENSE file for details

🔗 Related Projects

CargoShipper MCP - Infrastructure automation MCP server
Model Context Protocol - Official MCP documentation
FastMCP - Python MCP framework

💡 Tips & Best Practices

Writing Effective Procedures

Use numbered steps for sequential workflows
Include code examples in bash blocks
Document error recovery procedures
Add quality gates at key checkpoints
Use template variables for project-specific values

Organizing Projects

One config per project - Keep projects isolated
Shared procedures - Reference common workflows
Default project - Set for most common use case
Version control - Keep procedures in git

LLM Integration

Ask "what's next?" - Simple queries work best
Provide context - Mention current step if known
Query sections - Jump to specific workflow parts
List steps - Get overview before starting

🐛 Troubleshooting

"Project not found"

Check config file location
Verify filename format: <project>-config.json
Check ENGMANAGER_DEFAULT_PROJECT environment variable

"Procedure file not found"

Verify procedure_file path in config
Check procedures directory
Ensure markdown file exists

"Missing template variables"

Check procedure file for {VARIABLE} syntax
Add missing variables to config variables object
Variables must be UPPERCASE with underscores

"No projects configured"

Add at least one <project>-config.json file
Check config search paths
Verify JSON syntax in config files

📞 Support

Issues: GitHub Issues
Documentation: GitHub README
MCP Help: Model Context Protocol Docs

Made with ❤️ for better AI-assisted development workflows

Name		Name	Last commit message	Last commit date
Latest commit History 5 Commits
.github/workflows		.github/workflows
engmanager_mcp		engmanager_mcp
procedures		procedures
.gitignore		.gitignore
.mcp.json.example		.mcp.json.example
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.md		README.md
pyproject.toml		pyproject.toml
requirements.txt		requirements.txt
test_server.py		test_server.py
test_trowel.py		test_trowel.py

Folders and files

Latest commit

History

Repository files navigation

Engineering Manager MCP

🎯 Purpose

✨ Quick Start

Installation from PyPI

Configure in Claude Code

Create Your First Project

🔧 Available Tools

get_next_step

get_workflow_section

list_workflow_steps

list_available_projects

get_project_info

📚 Available Resources

engmanager://procedures/{project}

engmanager://config/{project}

engmanager://templates

engmanager://projects

🎨 Template Variables

📁 Project Structure

⚙️ Configuration

Environment Variables

Project Configuration Format

📖 Example Use Cases

Use Case 1: Consistent Git Workflow

Use Case 2: Multi-Project Development

Use Case 3: Onboarding Documentation

🔨 Development Setup

Local Installation

Development Mode with Claude Code

Testing

📦 Publishing to PyPI

Build Package

Upload to PyPI

Using GitHub Actions

🤝 Contributing

📄 License

🔗 Related Projects

💡 Tips & Best Practices

Writing Effective Procedures

Organizing Projects

LLM Integration

🐛 Troubleshooting

"Project not found"

"Procedure file not found"

"Missing template variables"

"No projects configured"

📞 Support

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 2

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`get_next_step`

`get_workflow_section`

`list_workflow_steps`

`list_available_projects`

`get_project_info`

`engmanager://procedures/{project}`

`engmanager://config/{project}`

`engmanager://templates`

`engmanager://projects`

Packages