# Amicus MCP Validation Protocol
**CRITICAL REQUIREMENT**: The amicus-mcp server MUST ALWAYS be validated before installation.
## Why This Matters
The Amicus MCP server is critical infrastructure:
- Multiple AI agents depend on it
- Breaking it breaks all connected sessions
- Installation errors waste significant development time
- Rollback is disruptive
**Never install without validation.**
## Pre-Installation Validation Checklist
Before running `uv tool install . --force` or any installation command:
### 1. Run Comprehensive Validation
```bash
./scripts/validate_before_install.sh
```
This script runs:
- ✓ Python syntax validation
- ✓ Module import test
- ✓ Server startup test
- ✓ Tool registration validation (15+ tools expected)
- ✓ Build package validation
- ✓ Test suite execution (if pytest available)
**ALL must pass before installation.**
### 2. Manual Verification (If Automated Fails)
If the automated script fails, run each check manually:
```bash
# Check syntax
python -m py_compile src/amicus/*.py
# Test import
python -c 'import sys; sys.path.insert(0, "src"); import amicus.server; print("OK")'
# Test server startup
timeout 3 python -m amicus
# Validate tools
python scripts/validate_tools.py
# Build and inspect package
python scripts/validate_build.py
```
### 3. Version Check
Always verify the version:
```bash
# Before installation
python -c 'import sys; sys.path.insert(0, "src"); from amicus import __version__; print(__version__)'
# After installation
amicus-mcp --version
```
## Safe Installation Workflow
### Step-by-Step Process
```bash
# 1. Validate FIRST
./scripts/validate_before_install.sh
# 2. Only if validation passes:
uv tool install . --force
# 3. Verify installation
~/.local/bin/amicus-mcp --version
~/.local/bin/amicus-mcp --list-tools
# 4. Check tool count (should be 15+)
~/.local/bin/amicus-mcp --list-tools | grep -c "^\d"
```
### If Validation Fails
**DO NOT INSTALL!**
1. Review the error output
2. Fix the issues in source code
3. Re-run validation
4. Only install after all checks pass
### If Installation Breaks Despite Validation
**Immediate Rollback:**
```bash
# Uninstall broken version
uv tool uninstall amicus-mcp
# Checkout last known good commit
git log --oneline | head -10 # Find last working commit
git checkout <commit-hash>
# Validate
./scripts/validate_before_install.sh
# Reinstall
uv tool install . --force
```
## What Gets Validated
### Tool Registration (validate_tools.py)
Ensures all expected tools are present:
**Core tools (v0.1.0+):**
- update_state, add_task, read_state
- broadcast_message, claim_task, complete_task
- is_safe_path, execute_safe_command
- heartbeat, toggle_tracking
**Cluster management (v0.3.0+):**
- register_node, get_best_model
**Anti-idle system (v0.4.0+):**
- set_agent_status, claim_best_task, assess_workload
**Minimum:** 15 tools must be registered.
### Build Package (validate_build.py)
Validates the wheel package:
1. Package builds successfully
2. All required source files included:
- amicus/__init__.py
- amicus/server.py
- amicus/cli.py
- amicus/core.py
- amicus/config.py
- amicus/monitor.py
- amicus/security.py
3. Package installs in clean environment
4. Package imports successfully
### Server Startup
Server must:
- Start without errors
- Initialize MCP protocol
- Load all modules
- Respond to basic queries
## Integration with Development Workflow
### Before Committing
Add to `.git/hooks/pre-commit`:
```bash
#!/bin/bash
./scripts/validate_before_install.sh
```
### Before Pull Requests
PR checklist must include:
- [ ] Validation script passes
- [ ] Tool count >= 15
- [ ] Server starts successfully
- [ ] All tests pass
### Before Releases
Release checklist must include:
- [ ] Full validation suite passes
- [ ] Version number updated
- [ ] CHANGELOG.md updated
- [ ] Installation tested on clean system
## Common Issues and Solutions
### Issue: "Tool count too low"
**Problem:** Some tools not being registered.
**Solutions:**
1. Check if `@mcp.tool()` decorators are present
2. Verify no syntax errors in tool definitions
3. Ensure all tool functions are at module level
4. Check imports are correct
### Issue: "Module not found"
**Problem:** Package not building correctly.
**Solutions:**
1. Check `pyproject.toml` `[tool.hatch.build.targets.wheel]`
2. Verify `packages = ["src/amicus"]` is correct
3. Ensure `src/amicus/__init__.py` exists
4. Run `python -m build` and inspect wheel contents
### Issue: "Server won't start"
**Problem:** Runtime error during initialization.
**Solutions:**
1. Check for import errors: `python -c 'import amicus.server'`
2. Review recent changes to `server.py`
3. Test with minimal imports
4. Check for circular dependencies
## Enforcement
This validation protocol is **mandatory** for:
- All commits to main branch
- All pull requests
- All releases
- All installations
**No exceptions.**
Violations will result in:
1. Immediate rollback
2. GitHub issue creation
3. Documentation of failure
4. Updated validation to catch the issue
## Version History
- v0.4.0: Validation protocol established
- Validation scripts created
- Governance documentation added
---
**Remember:** 5 minutes of validation saves hours of debugging broken installations.
