@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

$3

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

$3

`bash
npm install @itz4blitz/agentful-mcp-server
`

Configuration

$3

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

$3

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

$3

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

$3

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

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

$3

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

$3

Use the format: @+

Examples:
- next.js@14+typescript
- react@18+javascript
- vue@3+typescript
- django@5+python

$3

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