MCP server for agentful pattern learning with vector database
npm install @itz4blitz/agentful-mcp-serverMCP (Model Context Protocol) server for agentful pattern learning with vector database capabilities.
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
``bash`
/mcp add npx @itz4blitz/agentful-mcp-server
`bash`
npm install @itz4blitz/agentful-mcp-server
When using with agentful, the MCP server is automatically configured during npx @itz4blitz/agentful init.
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"
}
}
}
}
Store a successful code pattern or error fix for future reuse.
Parameters:
- code (string, required): The code pattern or fix code to storetech_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
}
Find similar patterns or error fixes by semantic similarity.
Parameters:
- query (string, required): Query text to search for similar patternstech_stack
- (string, required): Tech stack filterlimit
- (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"
}
]
}
Update success rate for a pattern or error fix.
Parameters:
- pattern_id (string, required): ID of the pattern or error fixsuccess
- (boolean, required): Whether the pattern was successful
Example:
`typescript`
{
"pattern_id": "pattern-123",
"success": true
}
Response:
`json`
{
"updated": true
}
Patterns are ranked using exponential moving average:
``
new_rate = 0.9 Ć old_rate + 0.1 Ć feedback
- Positive feedback (success: true): Increases success ratesuccess: false
- Negative feedback (): Decreases success rate
Use the format:
Examples:
- next.js@14+typescriptreact@18+javascript
- vue@3+typescript
- django@5+python
-
1. Patterns: Successful code implementations
2. Error Fixes: Error ā fix mappings for common issues
`bashInstall dependencies
npm install
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
``- 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%+)
- [ ] Persist database to disk
- [ ] True vector similarity search
- [ ] Pattern deduplication
- [ ] Export/import patterns
- [ ] Pattern analytics dashboard
MIT
Contributions welcome! Please read our contributing guidelines and submit pull requests to the main repository.
- Issues: https://github.com/itz4blitz/agentful/issues
- Documentation: https://agentful.app