npm package: @itz4blitz/agentful-mcp-server
Description: MCP server for agentful pattern learning with vector database
Author: agentful
Latest version: 2.0.0-beta.1

# @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)

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

### Option 2: Manual Installation

```bash
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):**
```json
{
  "mcpServers": {
    "agentful-patterns": {
      "command": "npx",
      "args": ["-y", "@itz4blitz/agentful-mcp-server"],
      "env": {
        "AGENTFUL_LOG_LEVEL": "debug"
      }
    }
  }
}
```

**Using local installation:**
```json
{
  "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:**
```typescript
// 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:**
```json
{
  "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:**
```typescript
{
  "query": "JWT authentication middleware",
  "tech_stack": "next.js@14+typescript",
  "limit": 3
}
```

**Response:**
```json
{
  "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:**
```typescript
{
  "pattern_id": "pattern-123",
  "success": true
}
```

**Response:**
```json
{
  "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

```bash
# 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

```bash
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