stack/packages/mosaic/framework/runtime/claude/context7-integration.md

Context7 Integration for Atomic Code Implementer

Overview

The atomic-code-implementer agent uses Context7 MCP server to dynamically fetch up-to-date documentation for libraries and frameworks. This integration provides real-time access to the latest API documentation, best practices, and code examples.

Integration Points

1. Preset-Driven Documentation Lookup

Each preset configuration includes a context7Libraries array that specifies which libraries to fetch documentation for:

{
  "context7Libraries": [
    "@nestjs/common",
    "@nestjs/core",
    "@nestjs/typeorm",
    "typeorm",
    "class-validator"
  ]
}

When a preset is loaded, the agent automatically resolves and fetches documentation for all specified libraries.

2. Error-Driven Documentation Lookup

When build errors, type errors, or runtime issues occur, the agent can automatically lookup documentation for:

• Error resolution patterns
• API migration guides
• Breaking change documentation
• Best practice guidelines

3. Implementation-Driven Lookup

During atomic task implementation, the agent can fetch:

• Framework-specific implementation patterns
• Library-specific configuration examples
• Performance optimization techniques
• Security best practices

Context7 Usage Patterns

Library Resolution

// Resolve library ID from preset configuration
const libraryId = await mcp__context7__resolve_library_id({
  libraryName: '@nestjs/common',
});

Documentation Retrieval

// Get comprehensive documentation
const docs = await mcp__context7__get_library_docs({
  context7CompatibleLibraryID: '/nestjs/nest',
  topic: 'controllers',
  tokens: 8000,
});

Error-Specific Lookups

// Look up specific error patterns
const errorDocs = await mcp__context7__get_library_docs({
  context7CompatibleLibraryID: '/typescript/typescript',
  topic: 'type errors',
  tokens: 5000,
});

Automatic Lookup Triggers

1. Preset Loading Phase

When an atomic task is started:

1. Detect tech stack from file extensions
2. Load appropriate preset configuration
3. Extract context7Libraries array
4. Resolve all library IDs
5. Fetch relevant documentation based on task context

2. Error Detection Phase

When quality hooks detect issues:

1. Parse error messages for library/framework references
2. Resolve documentation for problematic libraries
3. Look up error-specific resolution patterns
4. Apply common fixes based on documentation

3. Implementation Phase

During code implementation:

1. Detect new library imports or API usage
2. Automatically fetch documentation for unknown patterns
3. Provide implementation examples and best practices
4. Validate against latest API specifications

Context7 Library Mappings

NestJS Backend

{
  "@nestjs/common": "/nestjs/nest",
  "@nestjs/typeorm": "/nestjs/typeorm",
  "typeorm": "/typeorm/typeorm",
  "class-validator": "/typestack/class-validator",
  "bcrypt": "/kelektiv/node.bcrypt.js"
}

React Frontend

{
  "react": "/facebook/react",
  "react-dom": "/facebook/react",
  "@tanstack/react-query": "/tanstack/query",
  "tailwindcss": "/tailwindlabs/tailwindcss",
  "@testing-library/react": "/testing-library/react-testing-library"
}

Python FastAPI

{
  "fastapi": "/tiangolo/fastapi",
  "sqlalchemy": "/sqlalchemy/sqlalchemy",
  "pydantic": "/samuelcolvin/pydantic",
  "pytest": "/pytest-dev/pytest"
}

Integration Workflow

Sequential Thinking Enhanced Lookup

1. **Preset Analysis Phase**
   - Use sequential thinking to determine optimal documentation needs
   - Analyze task requirements for specific library features
   - Prioritize documentation lookup based on complexity

2. **Dynamic Documentation Loading**
   - Load core framework documentation first
   - Fetch specialized library docs based on task specifics
   - Cache documentation for session reuse

3. **Implementation Guidance**
   - Use retrieved docs to guide implementation decisions
   - Apply documented best practices and patterns
   - Validate implementation against official examples

Error Resolution Workflow

1. **Error Detection**
   - Parse error messages for library/API references
   - Identify deprecated or changed APIs
   - Extract relevant context from error stack traces

2. **Documentation Lookup**
   - Resolve library documentation for error context
   - Fetch migration guides for breaking changes
   - Look up troubleshooting and FAQ sections

3. **Automated Remediation**
   - Apply documented fixes and workarounds
   - Update code to use current APIs
   - Add proper error handling based on docs

Configuration Examples

Preset Configuration with Context7

{
  "name": "NestJS HIPAA Healthcare",
  "techStack": {
    "framework": "NestJS",
    "database": "TypeORM + PostgreSQL"
  },
  "context7Libraries": ["@nestjs/common", "@nestjs/typeorm", "typeorm", "bcrypt", "helmet"],
  "context7Topics": {
    "security": ["authentication", "authorization", "encryption"],
    "database": ["migrations", "relationships", "transactions"],
    "testing": ["unit tests", "integration tests", "mocking"]
  },
  "context7AutoLookup": {
    "onError": true,
    "onImport": true,
    "onDeprecation": true
  }
}

Agent Integration Points

## Context7 Integration in atomic-code-implementer.md

### Phase 1: Preset Loading

```javascript
// Load preset and resolve documentation
const preset = loadPreset(detectedTechStack, domainContext);
const libraryDocs = await loadContext7Documentation(preset.context7Libraries);
```

Phase 2: Implementation Guidance

// Get implementation examples during coding
const implementationDocs = await mcp__context7__get_library_docs({
  context7CompatibleLibraryID: '/nestjs/nest',
  topic: 'controllers authentication',
  tokens: 6000,
});

Phase 3: Error Resolution

// Look up error-specific documentation
if (buildError.includes('TypeError: Cannot read property')) {
  const errorDocs = await mcp__context7__get_library_docs({
    context7CompatibleLibraryID: extractLibraryFromError(buildError),
    topic: 'common errors troubleshooting',
    tokens: 4000,
  });
}

## Best Practices

### 1. Documentation Caching
- Cache resolved library IDs for session duration
- Store frequently accessed documentation locally
- Implement intelligent cache invalidation

### 2. Context-Aware Lookups
- Tailor documentation queries to specific atomic task context
- Use targeted topics rather than generic documentation
- Prioritize relevant sections based on implementation needs

### 3. Error-Driven Learning
- Maintain error pattern → documentation mapping
- Learn from successful error resolutions
- Build knowledge base of common issues and solutions

### 4. Performance Optimization
- Batch documentation requests when possible
- Use appropriate token limits for different use cases
- Implement request deduplication

## Troubleshooting

### Common Issues

1. **Library Not Found**
   ```javascript
   // Fallback to generic search
   const fallbackId = await mcp__context7__resolve_library_id({
     libraryName: `${libraryName} documentation`
   });

2. Documentation Too Generic

   // Use more specific topics
   const specificDocs = await mcp__context7__get_library_docs({
     context7CompatibleLibraryID: libraryId,
     topic: `${specificFeature} implementation examples`,
     tokens: 8000,
   });
   

3. Rate Limiting

   // Implement exponential backoff
   const docs = await retryWithBackoff(() => mcp__context7__get_library_docs(params));
   

This integration ensures the atomic code implementer always has access to the most current and relevant documentation, enabling it to produce high-quality, up-to-date implementations while following current best practices.