From 57b7dcf3a989ef54b8920daa7e3959c9b7936eb3 Mon Sep 17 00:00:00 2001 From: Chris Date: Sat, 30 Nov 2024 17:25:09 +0000 Subject: [PATCH 1/2] Update Claude/MCP blog post with setup instructions, API details, and pair programming guidance --- .../2024-11-30-using-claude-with-mcp/index.md | 288 ++++++++++-------- 1 file changed, 165 insertions(+), 123 deletions(-) diff --git a/blog/2024-11-30-using-claude-with-mcp/index.md b/blog/2024-11-30-using-claude-with-mcp/index.md index e61051a..7ac05df 100644 --- a/blog/2024-11-30-using-claude-with-mcp/index.md +++ b/blog/2024-11-30-using-claude-with-mcp/index.md @@ -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 @@ -23,180 +23,222 @@ 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. +## 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 +```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 Capabilities +### Key Limitations +- No direct repository deletion +- No branch deletion +- No issue updates or closures +- No comment management +- No direct merge capabilities -Claude Desktop can: +## Effective Pair Programming with Claude +Working with Claude through MCP requires understanding the division of responsibilities: + +### Claude's Role ✅ **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 +- Create and plan initial structures +- Generate code and documentation +- Create issues and PRs +- Provide code reviews +- Handle file operations +- Follow repository conventions ❌ **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 +- 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] + ``` + +2. **Communication Flow**: + - Explicitly state task requirements + - Define success criteria + - Clarify any assumptions + - Document decisions -## Practical Example: AI Metadata Implementation +3. **Error Prevention**: + - Check API capabilities before operations + - Validate generated content + - Use descriptive commit messages + - Document manual steps needed -Let's look at how we used Claude Desktop with MCP to implement our AI metadata feature: +## Real-World Example: AI Metadata Implementation -### 1. Issue Creation +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" }); -``` -### 2. Branch Management +// Human reviews and refines the issue +``` +### 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. \ No newline at end of file +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. Date: Sat, 30 Nov 2024 17:30:50 +0000 Subject: [PATCH 2/2] Fix MDX formatting and structure --- .../2024-11-30-using-claude-with-mcp/index.md | 87 ++++++++++--------- 1 file changed, 47 insertions(+), 40 deletions(-) diff --git a/blog/2024-11-30-using-claude-with-mcp/index.md b/blog/2024-11-30-using-claude-with-mcp/index.md index 7ac05df..ff05a40 100644 --- a/blog/2024-11-30-using-claude-with-mcp/index.md +++ b/blog/2024-11-30-using-claude-with-mcp/index.md @@ -31,32 +31,33 @@ In this post, we'll explore how to use Claude Desktop with the Model Context Pro To use Claude Desktop with the MCP GitHub Server, you'll need: -1. **Environment Setup**: +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**: +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 @@ -66,6 +67,7 @@ To use Claude Desktop with the MCP GitHub Server, you'll need: The Model Context Protocol GitHub Server provides a specific set of functions for GitHub interaction: ### Available Functions + ```typescript // Repository Operations search_repositories(query: string) @@ -97,7 +99,8 @@ create_pull_request(owner: string, repo: string, title: string, body: string) Working with Claude through MCP requires understanding the division of responsibilities: ### Claude's Role -✅ **Can Do**: + +Can Do: - Create and plan initial structures - Generate code and documentation - Create issues and PRs @@ -105,7 +108,7 @@ Working with Claude through MCP requires understanding the division of responsib - Handle file operations - Follow repository conventions -❌ **Cannot Do**: +Cannot Do: - Merge pull requests - Delete content - Update or close issues @@ -113,19 +116,20 @@ Working with Claude through MCP requires understanding the division of responsib - Access private repositories without setup ### Human Partner's Role -1. **Repository Management**: + +1. **Repository Management:** - Merge pull requests - Close completed issues - Delete branches when needed - Handle repository settings -2. **Quality Control**: +2. **Quality Control:** - Review generated content - Test implementations - Verify security aspects - Validate business logic -3. **Process Management**: +3. **Process Management:** - Guide overall direction - Make architectural decisions - Handle access controls @@ -134,23 +138,24 @@ Working with Claude through MCP requires understanding the division of responsib ## 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] - ``` - -2. **Communication Flow**: + +```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] +``` + +2. **Communication Flow:** - Explicitly state task requirements - Define success criteria - Clarify any assumptions - Document decisions -3. **Error Prevention**: +3. **Error Prevention:** - Check API capabilities before operations - Validate generated content - Use descriptive commit messages @@ -161,6 +166,7 @@ Working with Claude through MCP requires understanding the division of responsib Let's look at how we collaborated on the AI metadata feature: ### 1. Issue Creation + ```typescript // Claude creates the issue create_issue({ @@ -175,6 +181,7 @@ create_issue({ ``` ### 2. Implementation Flow + ```typescript // Claude creates the branch create_branch({ @@ -241,4 +248,4 @@ Effective collaboration with Claude via MCP GitHub Server requires: 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. -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.