npm package: @pod-mcp/groupfund-docs
Description: MCP server for GroupFund documentation, task management, and rule enforcement - Updated October 2025
Author: Pod MCP Team
Latest version: 2.0.1

# 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](./AGENT-USAGE.md)** - Comprehensive guide for AI agents on how to use this MCP server
- **[INTEGRATION.md](./INTEGRATION.md)** - Integration guide for setting up with Cursor/Claude
- **[RULES.md](./RULES.md)** - Complete reference of all project rules and validation

## Quick Start

### 1. Installation

```bash
cd docs-mcp-server
bun install
```

### 2. Configuration

Copy the example environment file and configure:

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

### 3. Build and Run

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

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

```typescript
// 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

```typescript
// 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

```typescript
// 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

```typescript
// 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

```typescript
// 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

```typescript
// 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

```typescript
// 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

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

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