# GitHub Issues Workflow
## Overview
The Amicus MCP server integrates seamlessly with GitHub Issues through the GitHub MCP provider. This integration enables agents to create, manage, and sync GitHub Issues with the local task management system.
## Architecture
The GitHub workflow integration uses:
- **GitHub MCP Tools**: Provided by the external GitHub MCP server
- **Amicus Task System**: Built-in task management via `add_task`, `claim_task`, `complete_task`
- **Context Bus**: State persistence layer for coordinating between agents and tracking work
## Available GitHub Operations
### Reading Issues
```python
# Get a specific issue
mcp__github__get_issue(owner="org", repo="project", issue_number=123)
# List issues with filters
mcp__github__list_issues(
owner="org",
repo="project",
state="open", # open, closed, or all
labels=["bug", "feature"],
sort="created", # created, updated, or comments
direction="desc" # asc or desc
)
```
### Creating Issues
```python
# Create a new issue
mcp__github__create_issue(
owner="org",
repo="project",
title="Issue title",
body="Detailed description",
labels=["enhancement"],
assignees=["username"]
)
```
### Updating Issues
```python
# Add a comment
mcp__github__add_issue_comment(
owner="org",
repo="project",
issue_number=123,
body="Comment text"
)
# Update issue state or metadata
mcp__github__update_issue(
owner="org",
repo="project",
issue_number=123,
state="closed", # open or closed
title="Updated title",
body="Updated description",
labels=["bug", "fixed"]
)
```
## Workflow Patterns
### Pattern 1: Manual Issue Import
Import a GitHub issue into the local task context when needed:
```python
# 1. Fetch issue details
issue = mcp__github__get_issue(owner="org", repo="project", issue_number=42)
# 2. Create local task
mcp__amicus-mcp__add_task(
task_description=f"GitHub Issue #{issue['number']}: {issue['title']} - {issue['html_url']}",
priority="high"
)
# 3. Work on the task
mcp__amicus-mcp__claim_task(task_index=N, agent_id="Node-X")
mcp__amicus-mcp__complete_task(task_index=N, agent_id="Node-X", outcome="Description")
# 4. Update GitHub issue
mcp__github__add_issue_comment(
owner="org",
repo="project",
issue_number=42,
body="Task completed. Details: ..."
)
```
### Pattern 2: Agent-Created Issues
Agents can create issues directly for feature requests or bug reports:
```python
# Create issue from agent
result = mcp__github__create_issue(
owner="org",
repo="project",
title="Feature: Add automated testing",
body="""
## Objective
Implement automated testing framework
## Requirements
- Unit tests
- Integration tests
- CI/CD integration
**Created by:** Amicus Agent Node-X
""",
labels=["enhancement", "testing"]
)
# Optionally import to local context
mcp__amicus-mcp__add_task(
task_description=f"GitHub Issue #{result['number']}: {result['title']}",
priority="medium"
)
```
### Pattern 3: Bidirectional Sync
Maintain synchronization between local tasks and GitHub issues:
```python
# When completing a local task linked to a GitHub issue
task_completed = mcp__amicus-mcp__complete_task(
task_index=5,
agent_id="Node-Y",
outcome="Successfully implemented feature"
)
# Post completion to GitHub
mcp__github__add_issue_comment(
owner="org",
repo="project",
issue_number=42,
body=f"Task completed by {agent_id}: {outcome}"
)
# Optionally close the issue
mcp__github__update_issue(
owner="org",
repo="project",
issue_number=42,
state="closed"
)
```
## Best Practices
### 1. Default Behavior: On-Demand Import
**Do not** automatically import all GitHub issues into local task context. This prevents task list pollution.
**Instead:** Only import issues when:
- Explicitly requested by a human
- Actively being worked on
- Part of current sprint/milestone
### 2. Agent Attribution
When agents create or comment on issues, always include attribution:
```markdown
**Created by:** Amicus Agent Node-Developer-001
*Generated in the Amicus Synapse cluster*
```
### 3. Link Preservation
Always include the GitHub issue URL in local task descriptions:
```python
task_description=f"GitHub Issue #{num}: {title} - https://github.com/owner/repo/issues/{num}"
```
### 4. Status Synchronization
When closing a task that corresponds to a GitHub issue:
1. Post a completion comment to the issue
2. Update issue state if appropriate
3. Include outcome details in the comment
### 5. Label Management
Use consistent labels for agent-created issues:
- `agent-created` - Created by an agent
- `automated` - Automated workflow
- `synapse-task` - Linked to amicus task
## Security Considerations
### Authentication
GitHub operations require proper authentication configured in your MCP settings. Ensure:
- GitHub token has appropriate permissions
- Token is stored securely (not in code)
- Token scopes are minimal (repo, issues)
### Sensitive Data
Never post sensitive information to public GitHub issues:
- API keys or credentials
- Internal system details
- Private user data
- Security vulnerabilities (use private security advisories)
## Configuration
### GitHub MCP Server Setup
Add to your `.github/mcp.json`:
```json
{
"mcpServers": {
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_TOKEN": "${GITHUB_TOKEN}"
}
}
}
}
```
### Repository Configuration
Set default repository in your environment or configuration:
```bash
export GITHUB_REPO_OWNER="your-org"
export GITHUB_REPO_NAME="your-project"
```
## Testing
### Test Checklist
- [ ] Can create issues from agents
- [ ] Can import issues to local tasks
- [ ] Can claim and complete imported tasks
- [ ] Can post completion updates to issues
- [ ] Can close issues programmatically
- [ ] Task status properly persists
- [ ] GitHub updates reflect in issue timeline
### Example Test Flow
See [GitHub Issue #3](https://github.com/earchibald/amicus-mcp/issues/3) and [Issue #4](https://github.com/earchibald/amicus-mcp/issues/4) for complete test examples.
## Troubleshooting
### Issue: GitHub operations fail with authentication error
**Solution:** Verify your GitHub token is valid and has the correct scopes:
```bash
gh auth status
```
### Issue: Tasks not syncing to GitHub
**Solution:** Ensure you're explicitly calling the sync operations. The system does not auto-sync by default (by design).
### Issue: Cannot find issues in local task list
**Solution:** Issues must be manually imported. Use the Pattern 1 workflow above.
## Future Enhancements
Potential improvements to the workflow:
1. **Automatic sync mode** (opt-in): Auto-update issues when tasks complete
2. **Batch operations**: Import multiple issues at once
3. **Webhook integration**: React to GitHub events in real-time
4. **Issue templates**: Standardized formats for agent-created issues
5. **Milestone integration**: Sync GitHub milestones with task priorities
## Related Documentation
- [Synapse Protocol](SYNAPSE_PROTOCOL.md) - Core coordination concepts
- [Bootstrap Manager](BOOTSTRAP_MANAGER.md) - Cluster management
- [Anti-Idle System](ANTI_IDLE_SYSTEM.md) - Agent lifecycle management
---
**Last Updated:** 2026-02-02
**Maintained by:** Amicus Synapse Cluster
