CSVLOD-AI MCP Server

The CSVLOD-AI MCP (Model Context Protocol) Server is a meta-protocol implementation that brings the revolutionary efficiency of CSVLOD-AI Framework to the MCP ecosystem. It embodies sovereignty through local-first architecture while orchestrating other MCP servers intelligently.

🚀 Features

• Context Engineering Tools: Initialize, validate, and analyze CSVLOD contexts
• Local MCP Registry: Mirror and manage MCP servers locally for sovereignty
• Intelligent Orchestration: Automatically select and coordinate MCP servers
• Zero Remote Dependencies: Everything runs locally after initial setup
• 90% Efficiency Applied: CSVLOD optimization principles for MCP overhead

📦 Installation

NPM (Recommended)

npm install -g csvlod-ai-mcp-server

Docker

docker pull hamzaamjad/csvlod-mcp-server:latest

From Source

git clone https://github.com/hamzaamjad/csvlod-ai-framework
cd mcp-server
npm install
npm run build

🛠️ Available Tools

CSVLOD Tools

1. csvlod_init - Initialize CSVLOD framework in any project

   {
     "projectPath": "/path/to/project",
     "type": "basic" | "enterprise" | "minimal"
   }

2. csvlod_validate - Validate CSVLOD compliance

   {
     "path": "/path/to/validate",
     "strict": true
   }

3. csvlod_generate - Generate CSVLOD components

   {
     "component": "context" | "manifest" | "prompt" | "structure",
     "path": "/target/path",
     "options": {
       "framework": "react",
       "language": "typescript"
     }
   }

4. csvlod_analyze - Analyze context effectiveness

   {
     "path": "/path/to/analyze",
     "includeMetrics": true
   }

MCP Registry Tools

5. mcp_registry - Manage local MCP registry

   {
     "action": "sync" | "search" | "install" | "list",
     "query": "github-mcp",
     "localOnly": true
   }

6. mcp_orchestrate - Intelligently orchestrate MCP servers

   {
     "task": "Search for TODOs in my codebase and create GitHub issues",
     "preferLocal": true,
     "ephemeral": true
   }

🏗️ Architecture

Local-First Design

All MCP servers are cached locally in ~/.csvlod-ai/ ensuring:

• Complete offline functionality
• Data sovereignty
• No external dependencies
• Privacy by default

Context Engineering

The server applies CSVLOD principles to MCP:

• Rich context over complex prompts
• Structure enables capability
• Progressive enhancement
• Self-improving systems

🔧 Configuration

MCP Configuration (for Cursor, Claude, etc.)

{
  "mcpServers": {
    "csvlod-ai": {
      "command": "npx",
      "args": ["-y", "csvlod-ai-mcp-server"],
      "env": {
        "CSVLOD_LOCAL_ONLY": "true"
      }
    }
  }
}

Environment Variables

• CSVLOD_LOCAL_ONLY - Use only local registry (default: false)
• CSVLOD_CACHE_DIR - Custom cache directory (default: ~/.csvlod-ai)
• CSVLOD_REGISTRY_URL - Custom registry URL (for air-gapped environments)

💡 Usage Examples

Initialize a New Project with CSVLOD

// Tool: csvlod_init
{
  "projectPath": "./my-new-app",
  "type": "enterprise"
}

// Creates:
// - .context/ directory with full CSVLOD structure
// - AI-CONTEXT.md with project overview
// - AGENT-MANIFEST.yaml with capabilities

Orchestrate Multiple MCP Servers

// Tool: mcp_orchestrate
{
  "task": "Analyze my code for security issues and create a report",
  "preferLocal": true,
  "ephemeral": true
}

// Returns execution plan using:
// - filesystem-mcp for code reading
// - security-mcp for analysis
// - report-mcp for generation

Sync and Search Registry

// Tool: mcp_registry
{
  "action": "sync",
  "localOnly": false
}

// Then search:
{
  "action": "search",
  "query": "github"
}

🌟 Philosophy

The CSVLOD-AI MCP Server embodies:

1. Sovereignty First: Your tools, your data, your control
2. Context > Prompts: Rich structure enables AI effectiveness
3. Local > Remote: Everything cached locally for true ownership
4. Efficiency: 90% optimization principles applied to MCP
5. Simplicity: Zero dependencies, pure functionality

🧪 Comprehensive Testing & Validation

The CSVLOD-AI MCP Server features industry-leading test coverage with comprehensive validation of all 12 production MCP tools:

Test Coverage Summary

npm run test:coverage  # Full coverage report
npm run test:all       # Complete test suite with reporting

Test Statistics:

• 31 Core Functionality Tests ✅ (100% passing)
• 48 Individual Tool Tests (comprehensive tool validation)
• 12 Integration Workflow Tests (end-to-end scenarios)
• 15 Performance Benchmarks (framework claims validation)
• 18 Error Handling Tests (edge cases and error recovery)

Total: 124+ Test Cases validating every aspect of the framework

MCP Tools Validation ✅

All 12 production MCP tools are comprehensively tested and validated:

1. csvlod_init - Initialize CSVLOD-AI framework structure
2. csvlod_validate - Validate project CSVLOD compliance
3. csvlod_generate - Generate CSVLOD components
4. csvlod_analyze - Analyze context effectiveness
5. mcp_registry - Manage local MCP registry
6. mcp_orchestrate - Orchestrate MCP servers intelligently
7. swarm_init - Initialize agent swarm coordination
8. swarm_decompose - Decompose tasks into agent subtasks
9. swarm_status - Get agent swarm status
10. swarm_assign - Assign tasks to available agents
11. swarm_complete - Mark tasks as completed
12. swarm_tasks - Retrieve task details and filtering

Performance Validation ✅

Framework performance claims validated through automated benchmarking:

• Context Load Time: <5 seconds ✅
• Tool Execution: <2-3 seconds per operation ✅
• Concurrent Operations: Safe parallel execution ✅
• Memory Usage: Efficient resource management ✅

Test Infrastructure Features

Professional Testing Pipeline:

• Jest Configuration: ES module support with TypeScript
• Coverage Thresholds: 80% lines, 80% functions, 70% branches
• Performance Testing: Automated benchmark validation
• Test Sequencing: Optimized execution order
• Error Recovery: Comprehensive edge case handling
• CI/CD Ready: Production-grade test automation

Test Utilities:

// Automated test runner with comprehensive reporting
npm run test:validate  // Full validation with coverage check
npm run test:individual // Individual tool testing
npm run test:integration // End-to-end workflow testing
npm run test:performance // Performance benchmark testing

🤝 Contributing

1. Fork the repository
2. Create your feature branch
3. Implement following CSVLOD principles
4. Ensure local-first architecture
5. Submit PR with context

📚 Documentation

• CSVLOD Framework Guide
• MCP Protocol Spec
• Integration Examples

📄 License

MIT License - Free forever, as sovereignty demands.

Created by Hamza Amjad
Part of the CSVLOD-AI Framework revolutionizing AI-native development

"Context > Prompts. Sovereignty > Dependence. Local > Remote."