Skip to content

Commit

Permalink
Merge pull request #45 from amiable-dev/post/update-claude-mcp-content
Browse files Browse the repository at this point in the history 
Update Claude/MCP blog post with enhanced documentation and pair programming guide
  • Loading branch information
@amiable-dev
amiable-dev authored Nov 30, 2024
2 parents 27c825b + 5178f2e commit ef42d7a
Showing 1 changed file with 172 additions and 123 deletions.
295 changes: 172 additions & 123 deletions blog/2024-11-30-using-claude-with-mcp/index.md
View file
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
---
title: Using Claude Desktop with MCP GitHub Server
authors: [claude]
tags: [claude, mcp, github, development]
description: A practical guide to using Claude Desktop with Model Context Protocol GitHub Server for repository management
tags: [claude, mcp, github, development, pair-programming]
description: A practical guide to using Claude Desktop with Model Context Protocol GitHub Server for repository management, including setup, best practices, and effective pair programming strategies
slug: using-claude-with-mcp
image: /img/claude-mcp.png
ai_generated: true
Expand All @@ -23,180 +23,229 @@ ai_quality_metrics:
technical_depth: 0.90
---

In this post, we'll explore how to use Claude Desktop with the Model Context Protocol (MCP) GitHub Server to manage repository changes effectively. We'll use our recent implementation of AI metadata in Docusaurus as a practical example.
In this post, we'll explore how to use Claude Desktop with the Model Context Protocol (MCP) GitHub Server to manage repository changes effectively. We'll cover setup, capabilities, limitations, and effective pair programming strategies, using our recent implementation of AI metadata in Docusaurus as a practical example.

<!--truncate-->

## Setting Up Claude Desktop with MCP

To use Claude Desktop with the MCP GitHub Server, you'll need:

1. **Environment Setup:**
- Claude Desktop with MCP support enabled
- MCP GitHub Server running locally or accessible
- GitHub repository access configured

2. **Configuration Steps:**

```yaml
# Example MCP configuration
protocol:
version: "1.0"
servers:
- type: "github"
url: "http://localhost:3000" # or your server URL
functions:
- search_repositories
- create_repository
- get_file_contents
- create_or_update_file
- push_files
- create_issue
- create_pull_request
- fork_repository
- create_branch
```
3. **Function Availability:**
- List available functions in your environment
- Review function parameters and limitations
- Test basic operations before complex tasks
## Understanding MCP GitHub Server
The Model Context Protocol GitHub Server provides an interface for AI models to interact with GitHub repositories. Key features include:
The Model Context Protocol GitHub Server provides a specific set of functions for GitHub interaction:
- Repository management
- Branch creation and updates
- File operations
- Issue and PR management
### Available Functions
## Claude Desktop Capabilities
```typescript
// Repository Operations
search_repositories(query: string)
create_repository(name: string, options?: RepoOptions)
fork_repository(owner: string, repo: string)

// File Operations
get_file_contents(owner: string, repo: string, path: string)
create_or_update_file(owner: string, repo: string, path: string, content: string)
push_files(owner: string, repo: string, files: File[])

// Branch Operations
create_branch(owner: string, repo: string, branch: string)

// Issue and PR Management
create_issue(owner: string, repo: string, title: string, body: string)
create_pull_request(owner: string, repo: string, title: string, body: string)
```
Claude Desktop can:
### Key Limitations
- No direct repository deletion
- No branch deletion
- No issue updates or closures
- No comment management
- No direct merge capabilities
## Effective Pair Programming with Claude
Working with Claude through MCP requires understanding the division of responsibilities:
### Claude's Role
Can Do:
- Create and plan initial structures
- Generate code and documentation
- Create issues and PRs
- Provide code reviews
- Handle file operations
- Follow repository conventions
Cannot Do:
- Merge pull requests
- Delete content
- Update or close issues
- Handle sensitive operations
- Access private repositories without setup
### Human Partner's Role
1. **Repository Management:**
- Merge pull requests
- Close completed issues
- Delete branches when needed
- Handle repository settings
2. **Quality Control:**
- Review generated content
- Test implementations
- Verify security aspects
- Validate business logic
3. **Process Management:**
- Guide overall direction
- Make architectural decisions
- Handle access controls
- Manage deployment
## Best Practices for Collaboration
1. **Clear Task Division**
```mermaid
graph TD
A[Task Identification] --> B[Capability Assessment]
B --> C{Who Handles?}
C -->|Claude| D[Generation & Creation]
C -->|Human| E[Review & Management]
D --> F[PR Creation]
E --> G[PR Merge & Cleanup]
```

✅ **Can Do**:
- Create and manage GitHub issues
- Create and switch branches
- Create and update files
- Generate pull requests
- Provide code reviews and suggestions
- Handle multiple files and changes
- Follow repository structure conventions
2. **Communication Flow:**
- Explicitly state task requirements
- Define success criteria
- Clarify any assumptions
- Document decisions

❌ **Cannot Do**:
- Directly merge pull requests
- Delete repositories or branches
- Access private repositories without proper setup
- Handle binary files or large assets
- Execute commands on your system
3. **Error Prevention:**
- Check API capabilities before operations
- Validate generated content
- Use descriptive commit messages
- Document manual steps needed

## Practical Example: AI Metadata Implementation
## Real-World Example: AI Metadata Implementation

Let's look at how we used Claude Desktop with MCP to implement our AI metadata feature:
Let's look at how we collaborated on the AI metadata feature:

### 1. Issue Creation

```typescript
// Creating an issue via MCP
// Claude creates the issue
create_issue({
title: "Add AI metadata components",
body: "Detailed requirements and tasks...",
body: "Detailed requirements...",
labels: ["enhancement"],
repo: "amiable-docusaurus",
owner: "amiable-dev"
});

// Human reviews and refines the issue
```

### 2. Branch Management
### 2. Implementation Flow

```typescript
// Creating a feature branch
// Claude creates the branch
create_branch({
repo: "amiable-docusaurus",
owner: "amiable-dev",
branch: "feature/ai-metadata-component"
});
```

### 3. File Operations

```typescript
// Creating/updating files
// Claude implements components
push_files({
repo: "amiable-docusaurus",
owner: "amiable-dev",
branch: "feature/ai-metadata-component",
files: [{
path: "src/theme/BlogPost/Header/AIMetadata/index.tsx",
content: "// Component code..."
content: "// Component implementation"
}],
message: "Add AI metadata component"
});
```

## Best Practices

1. **Branch Management**
- Create descriptive branch names
- Branch from the correct parent
- Keep changes focused

2. **Commit Organization**
- Write clear commit messages
- Group related changes
- Include context where needed

3. **Error Handling**
- Handle API limitations gracefully
- Retry failed operations
- Provide clear error messages

4. **Documentation**
- Document process flows
- Explain configuration requirements
- Include examples
// Human reviews and provides feedback
// Claude makes adjustments based on feedback
// Human handles final merge and cleanup
```

## Common Challenges and Solutions

1. **API Rate Limits**
- Use batched operations
- Implement proper error handling
- Add retry logic
1. **API Limitations**
- Challenge: Cannot update/close issues
- Solution: Document what needs manual handling
- Example: "These issues need manual closure: #18, #23"

2. **Branch Management**
- Verify branch existence
- Check parent branches
- Handle conflicts
2. **Work Coordination**
- Challenge: Complex multi-step processes
- Solution: Clear task breakdown and handoff points
- Example: Claude creates PR, signals for review

3. **File Operations**
- Handle encoding correctly
- Validate content types
- Check file sizes
3. **Content Management**
- Challenge: Large file changes
- Solution: Break into smaller, focused updates
- Example: Component structure first, then implementation

## Workflow Tips

1. **Planning**
- Break down tasks
- Create clear issues
- Define success criteria
- Define clear boundaries for automated vs manual tasks
- Document required manual interventions
- Set up clear success criteria

2. **Implementation**
- Use proper branching
- Commit logically
- Test thoroughly

3. **Review**
- Check generated code
- Verify documentation
- Test functionality

## Example Workflow

1. Create an issue:
```bash
# Using MCP GitHub Server
create_issue({
title: "Feature implementation",
body: "Requirements and tasks"
});
```

2. Create a feature branch:
```bash
create_branch({
branch: "feature/new-feature"
});
```
- Start with capability verification
- Use descriptive commit messages
- Include context in PR descriptions

3. Make changes:
```bash
push_files({
files: [/* file changes */],
message: "Implement feature"
});
```

4. Create PR:
```bash
create_pull_request({
title: "Add new feature",
body: "Description and context"
});
```
3. **Review Process**
- Human partner reviews all generated content
- Test functionality thoroughly
- Document any manual steps needed

## Conclusion

Using Claude Desktop with MCP GitHub Server provides a powerful way to manage repository changes. Key takeaways:
Effective collaboration with Claude via MCP GitHub Server requires:
1. Understanding available functions and limitations
2. Clear division of responsibilities
3. Good communication about manual steps
4. Regular validation and review

1. Understand capabilities and limitations
2. Follow best practices
3. Handle errors gracefully
4. Document thoroughly
By following these practices and understanding the capabilities and limitations of both Claude and the MCP GitHub Server, teams can maintain efficient workflows while ensuring quality and security.

This approach has helped us maintain clean repository history and efficient development workflows. The AI metadata implementation serves as a practical example of how these tools can work together effectively.
Our experience implementing the AI metadata feature demonstrates how this partnership can work effectively, with each party handling the tasks they're best suited for.

0 comments on commit ef42d7a

Please sign in to comment.