ChatFund Documentation MCP Server

A Model Context Protocol (MCP) server that provides intelligent access to ChatFund's documentation, task management, and rule enforcement capabilities for AI agents.

Features

• Document Ingestion & Indexing: Automatically processes and indexes all Markdown documentation
• Semantic Search: Vector-based search using AI Gateway embeddings for intelligent document retrieval
• Task Management: Create, track, and update agent tasks with full lifecycle management
• Rule Enforcement: Validates agent actions against project rules and ADRs
• Context Injection: Automatically provides relevant documentation context for agent operations
• ADR Tracking: Manages Architectural Decision Records with template validation
• Real-time Updates: Monitors document changes and updates indexes automatically

Architecture

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   AI Agent      │◄──►│   MCP Server     │◄──►│   Database      │
│   (Cursor)      │    │                  │    │   (SQLite)      │
└─────────────────┘    └──────────────────┘    └─────────────────┘
                              │
                              ▼
                       ┌──────────────────┐
                       │   Document       │
                       │   Processor      │
                       └──────────────────┘
                              │
                              ▼
                       ┌──────────────────┐
                       │   Search &       │
                       │   Embeddings     │
                       └──────────────────┘

Documentation

• AGENT-USAGE.md - Comprehensive guide for AI agents on how to use this MCP server
• INTEGRATION.md - Integration guide for setting up with Cursor/Claude
• RULES.md - Complete reference of all project rules and validation

Quick Start

1. Installation

cd docs-mcp-server
bun install

2. Configuration

Copy the example environment file and configure:

cp env.example .env
# Edit .env with your settings

3. Build and Run

# Build the project
bun run build

# Run in development mode
bun run dev

# Run in production mode
bun run start

4. Ingest Documentation

The server will automatically ingest your documentation on first run. You can also trigger ingestion manually:

# Using the MCP client (when connected)
# Call the 'ingest_docs' tool

Configuration

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | DOCS_PATH | Path to documentation directory | ../docs | | ADR_PATH | Path to ADR directory | ../adr | | CONTEXT_PATH | Path to context files | ../docs/context | | DATABASE_PATH | SQLite database file path | ./data/docs-mcp.db | | AI_GATEWAY_API_KEY | Vercel AI Gateway API key for embeddings | - | | EMBEDDING_MODEL | Embedding model via AI Gateway | voyage/voyage-3.5-lite | | CODE_EMBEDDING_MODEL | Code embedding model via AI Gateway | voyage/voyage-code-3 | | MAX_SEARCH_RESULTS | Maximum search results | 20 | | ENABLE_SEMANTIC_SEARCH | Enable semantic search | true | | ENABLE_RULE_ENFORCEMENT | Enable rule enforcement | true | | LOG_LEVEL | Logging level | info |

Document Types

The server automatically categorizes documents:

• ADR: Architectural Decision Records (adr/ directory)
• Context: Component context files (docs/context/ directory)
• PRD: Product Requirements Document
• Setup: Setup and installation guides
• User Flow: User flow documentation
• Other: General documentation

MCP Tools

Document Access

• search_docs: Search through documents and sections
• get_document: Retrieve specific documents with optional sections
• list_docs: List all available documents (resource)
• add_doc: Add a new document to the knowledge base
• update_doc: Update an existing document in the knowledge base

Task Management

• create_task: Create new agent tasks with specifications
• update_task: Update task status, results, and context
• close_task: Close/complete a task with optional result data
• pause_task: Pause a running task
• reopen_task: Reopen a completed or failed task
• next_task: Get the next available task to work on based on priority and dependencies
• list_tasks: List all tasks (resource)

ADR Management

• append_adr: Append content to ADR documents with template validation

Rule Enforcement

• validate_rules: Validate actions against project rules
• get_violations: Get current rule violations (resource)
• add_rule: Add a new custom validation rule to the rule engine
• update_rule: Update an existing custom rule
• delete_rule: Delete a custom rule (cannot delete core rules)
• list_rules: List all active rules in the rule engine

Activity Logging

• log_activity: Log an activity/action taken by the AI agent for future reference
• search_activities: Search through past activities with semantic search
• get_recent_activities: Get recent activities for current or specific session
• get_task_timeline: View task timeline (past/present/future tasks)

System Operations

• ingest_docs: Ingest and index documentation from filesystem

MCP Resources

Read-Only Resources

• docs://list - List all documents
• docs://search - Search interface
• tasks://list - List all tasks
• session://current - Current session context
• rules://violations - Current rule violations
• docs://document/{id} - Specific document content

Rule Engine

The server enforces critical project rules:

Critical Rules

1. Master Reference Rule: Must consult master.md and links.md before blockchain code
2. Project Structure Rule: Must follow established file organization
3. Technology Stack Rule: Must use approved dependencies
4. Development Workflow Rule: Must include tests and validation
5. Security Validation Rule: Must implement security measures
6. Context Navigation Rule: Must consult relevant context files

Rule Validation

Rules are automatically validated when:

• Creating tasks
• Executing actions
• Updating documentation
• Generating code

Usage Examples

Agent Integration

// Example agent usage
const mcpClient = new MCPClient('stdio', {
  command: 'node',
  args: ['dist/index.js']
});

// Search for documentation
const searchResults = await mcpClient.callTool('search_docs', {
  query: 'Squads v4 multisig implementation',
  topK: 5,
  semantic: true
});

// Create a task
const task = await mcpClient.callTool('create_task', {
  description: 'Implement Squads v4 vault deployment',
  docRefs: ['master.md', 'Blockchain-Context.md'],
  priority: 'high'
});

// Validate an action
const validation = await mcpClient.callTool('validate_rules', {
  action: 'create blockchain module',
  context: {
    component: 'blockchain',
    consultedDocs: ['master.md', 'Blockchain-Context.md']
  }
});

Document Search

// Semantic search
const results = await mcpClient.callTool('search_docs', {
  query: 'multisig vault deployment',
  topK: 10,
  docTypes: ['adr', 'context'],
  semantic: true
});

// Get specific document
const doc = await mcpClient.callTool('get_document', {
  docId: 'blockchain-context',
  includeSections: true
});

Rule Management

// Add a custom rule
const addRuleResult = await mcpClient.callTool('add_rule', {
  id: 'custom-validation-rule',
  name: 'Custom Validation Rule',
  description: 'Validates custom business logic',
  category: 'business',
  validationFunction: 'contains("custom")',
  severity: 'medium',
  enabled: true
});

// Update a rule
const updateRuleResult = await mcpClient.callTool('update_rule', {
  id: 'custom-validation-rule',
  name: 'Updated Custom Rule',
  severity: 'high'
});

// List all rules
const rules = await mcpClient.callTool('list_rules', {});

// Delete a custom rule
const deleteResult = await mcpClient.callTool('delete_rule', {
  id: 'custom-validation-rule'
});

Document Management

// Add a new document
const addDocResult = await mcpClient.callTool('add_doc', {
  id: 'new-document',
  title: 'New Document',
  content: 'This is the content of the new document.',
  type: 'context',
  tags: ['new', 'example'],
  metadata: { author: 'ai-agent' }
});

// Update an existing document
const updateDocResult = await mcpClient.callTool('update_doc', {
  id: 'new-document',
  title: 'Updated Document',
  content: 'This is the updated content.',
  tags: ['updated', 'example']
});

Task Management

// Create a task
const task = await mcpClient.callTool('create_task', {
  description: 'Implement user authentication system',
  priority: 'high',
  estimatedDuration: 120,
  docRefs: ['Auth-Context.md', 'Security-Context.md']
});

// Close/complete a task
const closeResult = await mcpClient.callTool('close_task', {
  taskId: task.taskId,
  result: { 
    implemented: ['login', 'logout', 'session management'],
    files: ['src/auth.ts', 'src/session.ts']
  },
  success: true
});

// Pause a running task
const pauseResult = await mcpClient.callTool('pause_task', {
  taskId: 'task-123',
  reason: 'Waiting for API key from user'
});

// Reopen a completed task
const reopenResult = await mcpClient.callTool('reopen_task', {
  taskId: 'task-123',
  reason: 'Additional requirements discovered'
});

// Get next available task
const nextTask = await mcpClient.callTool('next_task', {
  agentType: 'development',
  priority: 'high',
  excludeTypes: ['documentation']
});

// Update task status manually
const updateResult = await mcpClient.callTool('update_task', {
  taskId: 'task-123',
  status: 'running',
  context: { 
    currentStep: 'implementing core logic',
    progress: '25% complete'
  }
});

Development

Project Structure

docs-mcp-server/
├── src/
│   ├── types.ts              # Type definitions
│   ├── config.ts             # Configuration management
│   ├── logger.ts             # Structured logging
│   ├── database.ts           # SQLite database layer
│   ├── document-processor.ts # Markdown processing
│   ├── embeddings.ts         # AI Gateway embeddings
│   ├── search.ts             # Search functionality
│   ├── rule-engine.ts        # Rule validation
│   ├── mcp-server.ts         # Main MCP server
│   └── index.ts              # Entry point
├── tests/                    # Test files
├── data/                     # Database files
└── dist/                     # Built files

Adding New Rules

// In rule-engine.ts
this.addRule({
  id: 'custom-rule',
  name: 'Custom Rule',
  description: 'Description of the rule',
  severity: 'medium',
  validate: (input) => {
    // Validation logic
    if (violation) {
      return {
        ruleId: 'custom-rule',
        ruleName: 'Custom Rule',
        severity: 'medium',
        message: 'Violation message',
        suggestion: 'How to fix it',
        context: input.context
      };
    }
    return null;
  }
});

Adding New Tools

// In mcp-server.ts
case 'new_tool':
  return await this.handleNewTool(args);

private async handleNewTool(args: any): Promise<any> {
  // Tool implementation
  return {
    content: [{
      type: 'text',
      text: JSON.stringify(result, null, 2)
    }]
  };
}

Testing

# Run tests
bun test

# Run tests in watch mode
bun test:watch

# Type checking
bun run typecheck

# Linting
bun run lint

Monitoring

The server provides comprehensive logging and monitoring:

• Structured Logging: JSON-formatted logs with context
• Performance Metrics: Operation timing and statistics
• Error Tracking: Detailed error information with context
• Rule Violations: Tracking of rule violations and patterns

Security

• Input Validation: All inputs validated with Zod schemas
• Rule Enforcement: Prevents unauthorized actions
• Access Control: Session-based access management
• Audit Trail: Complete logging of all operations

Troubleshooting

Common Issues

1. Database Locked: Ensure no other processes are using the database
2. AI Gateway API Errors: Check API key and rate limits
3. Document Not Found: Verify document paths and ingestion
4. Rule Violations: Check rule configuration and context

Debug Mode

LOG_LEVEL=debug bun run dev

Contributing

1. Follow the established code patterns
2. Add tests for new functionality
3. Update documentation
4. Ensure all rules pass validation

License

MIT License - see LICENSE file for details.