Merge pull request #38 from amiable-dev/post/update-ai-metadata-blog

Update AI metadata implementation blog post
amiable-dev · Nov 30, 2024 · 27c825b · 27c825b
2 parents 866eb9b + 0b84682
commit 27c825b
Show file tree

Hide file tree

Showing 2 changed files with 362 additions and 2 deletions.
diff --git a/blog/2024-11-30-implementing-ai-metadata/index.md b/blog/2024-11-30-implementing-ai-metadata/index.md
@@ -23,4 +23,188 @@ ai_quality_metrics:
   technical_depth: 0.92
 ---
 
-[Previous content remains the same]
+As AI-assisted content creation becomes more prevalent, transparency about how content is created becomes increasingly important. This post explains how we implemented a comprehensive AI metadata system in our Docusaurus blog, following theme conventions and providing clear visibility into AI involvement in content creation.
+
+<!--truncate-->
+
+## The Implementation Journey
+
+Our journey to implement AI metadata tracking involved several key decisions and steps:
+
+1. Following Docusaurus theme conventions
+2. Using TypeScript for type safety
+3. Creating a clear component hierarchy
+4. Implementing proper metadata display
+
+### Theme Integration
+
+We chose to integrate our AI metadata display as a theme component following Docusaurus conventions:
+
+```text
+src/theme/
+  BlogPost/
+    Header/
+      AIMetadata/
+        index.tsx    # Main component
+        types.ts     # Type definitions
+```
+
+This structure allows for:
+- Clear organization
+- Easy swizzling
+- Future extensibility
+- Proper theme integration
+
+### Front Matter Structure
+
+We implemented a structured front matter format that captures essential information about AI involvement:
+
+```yaml
+---
+title: Your Blog Post Title
+authors: [claude]  # AI author attribution
+tags: [tag1, tag2]
+# AI Metadata Fields
+ai_generated: true
+ai_models: 
+  - name: "Claude 3.5 Sonnet"
+    version: "20241022"
+    tasks: ["content", "code"]
+    confidence_score: 0.95
+ai_tools:
+  - name: "Anthropic Messages API"
+    version: "2024-03"
+ai_review_process: "Human reviewed and edited"
+ai_quality_metrics:
+  accuracy: 0.95
+  coherence: 0.98
+  technical_depth: 0.92
+---
+```
+
+### TypeScript Implementation
+
+We use TypeScript interfaces to ensure type safety:
+
+```typescript
+interface AIModel {
+  name: string;
+  version: string;
+  tasks?: string[];
+  confidence_score?: number;
+}
+
+interface AITool {
+  name: string;
+  version: string;
+}
+
+interface QualityMetrics {
+  accuracy: number;
+  coherence: number;
+  technical_depth: number;
+  [key: string]: number;
+}
+
+interface AIMetadata {
+  ai_generated: boolean;
+  ai_models?: AIModel[];
+  ai_tools?: AITool[];
+  ai_review_process?: string;
+  ai_quality_metrics?: QualityMetrics;
+}
+```
+
+### Component Implementation
+
+The component is implemented as a swizzled theme component:
+
+```tsx
+import React from 'react';
+import BlogPostHeader from '@theme-original/BlogPost/Header';
+import type { WrapperProps } from '@docusaurus/types';
+import AIMetadata from './AIMetadata';
+
+export default function BlogPostHeaderWrapper(
+  props: WrapperProps<typeof BlogPostHeader>
+): JSX.Element {
+  return (
+    <>
+      <AIMetadata metadata={props.metadata} />
+      <BlogPostHeader {...props} />
+    </>
+  );
+}
+```
+
+## Integration Steps
+
+1. Install required dependencies:
+```bash
+npm install @docusaurus/theme-classic zod @headlessui/react
+```
+
+2. Swizzle the BlogPost Header (note the --wrap option):
+```bash
+npm run swizzle @docusaurus/theme-classic BlogPost/Header -- --wrap
+```
+
+3. Implement the component structure:
+```bash
+src/theme/
+  BlogPost/
+    Header/
+      AIMetadata/
+        index.tsx
+        types.ts
+    index.tsx
+```
+
+## Best Practices
+
+1. **Theme Integration**
+   - Use wrapping instead of ejection for better maintainability
+   - Follow Docusaurus naming conventions
+   - Keep components modular
+
+2. **Type Safety**
+   - Use TypeScript throughout
+   - Define clear interfaces
+   - Validate metadata structure
+
+3. **Component Organization**
+   - Follow theme hierarchy
+   - Keep related code together
+   - Use clear file naming
+
+4. **Documentation**
+   - Document component usage
+   - Explain integration steps
+   - Provide examples
+
+## Future Enhancements
+
+1. **Analytics Integration**
+   - Track AI content performance
+   - Monitor quality metrics
+   - Analyze user engagement
+
+2. **Advanced Features**
+   - Inline AI contributions
+   - Section-specific metadata
+   - Quality assessment tools
+
+3. **User Experience**
+   - Interactive tooltips
+   - Customizable displays
+   - Accessibility improvements
+
+## Conclusion
+
+Implementing AI metadata in Docusaurus helps maintain transparency while following best practices for theme development. The solution we've created is:
+- Type-safe
+- Maintainable
+- Extensible
+- Well-documented
+
+You can find the complete implementation in our [GitHub repository](https://github.com/amiable-dev/amiable-docusaurus), and we welcome contributions and suggestions for improvements.
diff --git a/blog/2024-11-30-using-claude-with-mcp/index.md b/blog/2024-11-30-using-claude-with-mcp/index.md
@@ -23,4 +23,180 @@ ai_quality_metrics:
   technical_depth: 0.90
 ---
 
-[Previous content remains the same]
+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.
+
+<!--truncate-->
+
+## Understanding MCP GitHub Server
+
+The Model Context Protocol GitHub Server provides an interface for AI models to interact with GitHub repositories. Key features include:
+
+- Repository management
+- Branch creation and updates
+- File operations
+- Issue and PR management
+
+## Claude Desktop Capabilities
+
+Claude Desktop can:
+
+✅ **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
+
+❌ **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
+
+## Practical Example: AI Metadata Implementation
+
+Let's look at how we used Claude Desktop with MCP to implement our AI metadata feature:
+
+### 1. Issue Creation
+
+```typescript
+// Creating an issue via MCP
+create_issue({
+  title: "Add AI metadata components",
+  body: "Detailed requirements and tasks...",
+  labels: ["enhancement"],
+  repo: "amiable-docusaurus",
+  owner: "amiable-dev"
+});
+```
+
+### 2. Branch Management
+
+```typescript
+// Creating a feature branch
+create_branch({
+  repo: "amiable-docusaurus",
+  owner: "amiable-dev",
+  branch: "feature/ai-metadata-component"
+});
+```
+
+### 3. File Operations
+
+```typescript
+// Creating/updating files
+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..."
+  }],
+  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
+
+## Common Challenges and Solutions
+
+1. **API Rate Limits**
+   - Use batched operations
+   - Implement proper error handling
+   - Add retry logic
+
+2. **Branch Management**
+   - Verify branch existence
+   - Check parent branches
+   - Handle conflicts
+
+3. **File Operations**
+   - Handle encoding correctly
+   - Validate content types
+   - Check file sizes
+
+## Workflow Tips
+
+1. **Planning**
+   - Break down tasks
+   - Create clear issues
+   - Define 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"
+});
+```
+
+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"
+});
+```
+
+## Conclusion
+
+Using Claude Desktop with MCP GitHub Server provides a powerful way to manage repository changes. Key takeaways:
+
+1. Understand capabilities and limitations
+2. Follow best practices
+3. Handle errors gracefully
+4. Document thoroughly
+
+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.