@itz4blitz/agentful-mcp-server

MCP (Model Context Protocol) server for agentful pattern learning with vector database capabilities.

Overview

This MCP server enables Claude Code to learn from successful code patterns and error fixes over time, storing them in a local database and retrieving them based on semantic similarity and tech stack.

Key Features:

• 🧠 Pattern Learning: Stores successful code patterns for future reuse
• 🔧 Error Fix Storage: Captures error → fix mappings for common issues
• 🎯 Tech Stack Filtering: Organizes patterns by tech stack (e.g., "next.js@14+typescript")
• 📊 Success Rate Tracking: Uses exponential moving average to rank patterns by effectiveness
• 🚀 Zero Dependencies: Pure JavaScript SQLite (sql.js) - no native compilation

Installation

Option 1: Via Claude Code MCP (Recommended)

/mcp add npx @itz4blitz/agentful-mcp-server

Option 2: Manual Installation

npm install @itz4blitz/agentful-mcp-server

Configuration

Automatic Configuration (Recommended)

When using with agentful, the MCP server is automatically configured during npx @itz4blitz/agentful init.

Manual Configuration

Add to your Claude Code MCP configuration (.claude/config.json):

Using npx (easiest):

{
  "mcpServers": {
    "agentful-patterns": {
      "command": "npx",
      "args": ["-y", "@itz4blitz/agentful-mcp-server"],
      "env": {
        "AGENTFUL_LOG_LEVEL": "debug"
      }
    }
  }
}

Using local installation:

{
  "mcpServers": {
    "agentful-patterns": {
      "command": "node",
      "args": ["./node_modules/@itz4blitz/agentful-mcp-server/dist/index.js"],
      "env": {
        "AGENTFUL_LOG_LEVEL": "debug"
      }
    }
  }
}

MCP Tools

1. store_pattern

Store a successful code pattern or error fix for future reuse.

Parameters:

• code (string, required): The code pattern or fix code to store
• tech_stack (string, required): Tech stack identifier (e.g., "next.js@14+typescript")
• error (string, optional): If provided, stores as error fix mapping

Example:

// Store a successful pattern
{
  "code": "const jwt = verifyToken(token);",
  "tech_stack": "next.js@14+typescript"
}

// Store an error fix
{
  "code": "const jwt = verifyToken(token);",
  "error": "JWT verification failed: invalid token",
  "tech_stack": "next.js@14+typescript"
}

Response:

{
  "pattern_id": "uuid-1234-5678-9012",
  "success": true
}

2. find_patterns

Find similar patterns or error fixes by semantic similarity.

Parameters:

• query (string, required): Query text to search for similar patterns
• tech_stack (string, required): Tech stack filter
• limit (number, optional): Maximum number of results (default: 5)

Example:

{
  "query": "JWT authentication middleware",
  "tech_stack": "next.js@14+typescript",
  "limit": 3
}

Response:

{
  "patterns": [
    {
      "id": "pattern-123",
      "type": "pattern",
      "code": "const jwt = verifyToken(token);",
      "success_rate": 0.95,
      "tech_stack": "next.js@14+typescript"
    },
    {
      "id": "error-fix-456",
      "type": "error_fix",
      "code": "const decoded = Buffer.from(token, 'base64');",
      "success_rate": 0.87,
      "tech_stack": "next.js@14+typescript"
    }
  ]
}

3. add_feedback

Update success rate for a pattern or error fix.

Parameters:

• pattern_id (string, required): ID of the pattern or error fix
• success (boolean, required): Whether the pattern was successful

Example:

{
  "pattern_id": "pattern-123",
  "success": true
}

Response:

{
  "updated": true
}

How It Works

Success Rate Tracking

Patterns are ranked using exponential moving average:

new_rate = 0.9 × old_rate + 0.1 × feedback

• Positive feedback (success: true): Increases success rate
• Negative feedback (success: false): Decreases success rate

Tech Stack Format

Use the format: <framework>@<version>+<language>

Examples:

• next.js@14+typescript
• react@18+javascript
• vue@3+typescript
• django@5+python

Pattern Types

1. Patterns: Successful code implementations
2. Error Fixes: Error → fix mappings for common issues

Development

# Install dependencies
npm install

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Build
npm run build

# Run in development mode
npm run dev

Architecture

┌─────────────────────────────────────────────┐
│              MCP Server                      │
├─────────────────────────────────────────────┤
│  Tools: store_pattern, find_patterns,       │
│         add_feedback                         │
├─────────────────────────────────────────────┤
│  PatternRepository  |  ErrorRepository      │
│  - Code patterns     |  Error → fix maps    │
├─────────────────────────────────────────────┤
│  EmbeddingService (Transformers.js)          │
│  - 384-dim vectors using all-MiniLM-L6-v2   │
├─────────────────────────────────────────────┤
│  DatabaseManager (sql.js)                    │
│  - In-memory SQLite                          │
│  - Patterns + error_fixes tables             │
└─────────────────────────────────────────────┘

Testing

The project has comprehensive test coverage:

• Unit Tests: PatternRepository, ErrorRepository, EmbeddingService
• Integration Tests: MCP tool end-to-end workflows
• 50 tests total, covering all major functionality

npm run test:coverage

Limitations

• Text-based search: Currently uses success_rate sorting instead of vector similarity (simplified for compatibility)
• In-memory database: Data is not persisted to disk (sql.js limitation)
• Embedding generation: Uses Transformers.js with 85% accuracy (vs OpenAI embeddings with 95%+)

Future Enhancements

• [ ] Persist database to disk
• [ ] True vector similarity search
• [ ] Pattern deduplication
• [ ] Export/import patterns
• [ ] Pattern analytics dashboard

License

MIT

Contributing

Contributions welcome! Please read our contributing guidelines and submit pull requests to the main repository.

Support

• Issues: https://github.com/itz4blitz/agentful/issues
• Documentation: https://agentful.app