ChittyMCP

!ChittyOS !Tier

ChittyMCP - Consolidated MCP Servers

Version 3.0.0 - Modular, consolidated Model Context Protocol servers for the ChittyOS ecosystem.

  

---

✨ What's New in v3.0.0

Modular Architecture - Completely refactored with:

• ✅ Core module with reusable MCP server base class
• ✅ Dynamic tool loading - add tools without touching core code
• ✅ Integration layer - centralized ChittyOS service clients
• ✅ Chain execution - multi-tool workflow orchestration
• ✅ 15+ tools across 4 domains (evidence, legal, infrastructure, sync)

New Structure: `` src/ ├── core/ # Shared utilities (BaseMCPServer, ToolLoader, ChainExecutor) ├── integration/ # Service clients (ChittyID, Cloudflare, Notion) ├── tools/ # Modular tools (evidence, legal, infrastructure, sync) └── servers/ # Server implementations (unified, evidence) ``

---

Status

| Component | Status | Description | |-----------|--------|-------------| | Core Module | ✅ Complete | BaseMCPServer, ToolLoader, ChainExecutor, Logger | | Integration Layer | ✅ Complete | ChittyID, Cloudflare, Notion clients | | Evidence Tools | ✅ Complete | 4 tools - fully implemented | | Legal Tools | ✅ Complete | 4 tools - ChittyID integration working | | Infrastructure Tools | ✅ Complete | 4 tools - Cloudflare API integration | | Sync Tools | ✅ Complete | 3 tools - device sync framework | | Unified Server | ✅ Complete | Dynamic loading, chain execution | | Evidence Server | ✅ Complete | Standalone server using modular tools |

---

Quick Start

Installation

# Install dependencies
npm install

Running Servers

# Unified server (all 15+ tools + chain execution)
npm start

# Evidence server only (4 tools)
npm start:evidence

# Development mode with auto-reload
npm run dev
npm run dev:evidence

Environment Variables

# ChittyOS Core
CHITTY_ID_TOKEN=<service token from ChittyID>
CHITTYID_SERVICE=https://id.chitty.cc
CHITTY_ENV=production

# Cloudflare (optional)
CLOUDFLARE_API_TOKEN=<api token>
CLOUDFLARE_ACCOUNT_ID=bbf9fcd845e78035b7a135c481e88541

# Notion (optional)
NOTION_TOKEN=<integration token>
NOTION_DATABASE_ID=<database id>

# Logging
LOG_LEVEL=INFO  # DEBUG|INFO|WARN|ERROR

---

Servers

1. Evidence Intake Server ✅

Purpose: Legal evidence processing for case management Case: Arias v. Bianchi (2024D007847) Status: Fully working

Tools (4):

• intake_evidence - Process and categorize evidence files
• list_evidence - Query evidence by category
• get_evidence_stats - Get case statistics
• start_intake_monitoring - Watch directory for new files

Features:

• SHA256 duplicate detection
• 14 evidence categories
• Chain of custody tracking
• Real-time file monitoring with chokidar
• Google Drive integration
• PostgreSQL registry (optional)

Evidence path: /Users/nb/Evidence-Intake/2024D007847-Arias-v-Bianchi/

Example: ``javascript // Intake evidence await intake_evidence({ files: ["/path/to/document.pdf"], category: "07_COURT_FILINGS", priority: "high" }); ``

---

2. Unified Consolidated Server 🟡

Purpose: Multi-domain MCP server with ChittyOS integration Status: Schema complete, implementations are mostly placeholders Version: 3.0.0

Tools (19) - organized by domain:

Executive (5) - ⚠️ Placeholder implementations

• analyze_performance - Returns mock performance data
• risk_assessment - Returns mock risk data
• make_executive_decision - Returns template decisions
• strategic_planning - Returns placeholder plans
• delegate_task - Returns mock task delegations

Legal (7) - 🟡 Partially implemented

• generate_chitty_id - ✅ Works (calls id.chitty.cc), has fallback
• create_legal_case - ⚠️ Placeholder
• analyze_document - ⚠️ Placeholder
• process_payment - ⚠️ Placeholder
• compliance_check - ⚠️ Placeholder
• search_cases - ⚠️ Placeholder
• execute_workflow - ⚠️ Placeholder

Infrastructure (4) - ⚠️ Placeholder implementations

• deploy_worker - Returns mock deployment results
• manage_kv_namespace - Returns mock KV operations
• manage_r2_bucket - Returns mock R2 operations
• execute_d1_query - Returns mock query results

Sync (3) - ⚠️ Placeholder implementations

• register_mcp_server - Returns mock registration
• sync_mcp_state - Returns mock sync status
• get_synced_servers - Returns empty list

Chain Workflows: 5 chains defined in config/chains.json but not fully orchestrated

---

3. MCP Execution Service ✅

Purpose: Remote tool execution and service discovery Language: TypeScript Status: Fully working

Tools (3):

• execute_remote_tool - Execute tools on remote MCP servers
• discover_services - List available services
• health_check - Check service health

Features:

• Retry logic with exponential backoff
• Service registry for ChittyOS endpoints
• Timeout handling
• Health monitoring

Services registered:

• chittyid → https://id.chitty.cc
• chittyregistry → https://registry.chitty.cc
• chittygateway → https://gateway.chitty.cc

Example: ``typescript await execute_remote_tool({ service: "chittyid", tool: "mint", arguments: { entity_type: "PEO" }, config: { timeout: 10000, retries: 3 } }); ``

---

Configuration

Claude Desktop Integration

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "chittymcp-unified": {
      "command": "node",
      "args": ["/absolute/path/to/chittymcp/src/servers/unified-server.js"],
      "env": {
        "CHITTY_ID_TOKEN": "${CHITTY_ID_TOKEN}",
        "CLOUDFLARE_API_TOKEN": "${CLOUDFLARE_API_TOKEN}",
        "LOG_LEVEL": "INFO"
      }
    },
    "evidence-intake": {
      "command": "node",
      "args": ["/absolute/path/to/chittymcp/src/servers/evidence-server.js"],
      "env": {}
    }
  }
}

Replace /absolute/path/to/ with your actual path.

Legacy servers (still functional):

• mcp-evidence-server/index.js → Use src/servers/evidence-server.js instead
• mcp-unified-consolidated/unified-server.js → Use src/servers/unified-server.js instead

---

Known Issues

1. OpenAI Package - package.json references wrong package name

• Fix: cd mcp-unified-consolidated && npm install openai@latest

1. Unified Server Tools - Most tools return placeholder/mock data

• Need real implementations for executive, infrastructure, and sync domains

1. Neon Auth - OAuth flow may timeout

• Run: neon auth login before using

1. Hardcoded Paths - Evidence server uses /Users/nb/Evidence-Intake

• Set EVIDENCE_BASE_PATH in .env to override

1. Missing .env - No environment file by default

• Copy .env.example and fill in credentials

---

Troubleshooting

See TROUBLESHOOTING.md for:

• Diagnostic script usage
• Common error fixes
• LaunchD service issues (macOS)
• Network timeout solutions
• Package dependency fixes

Quick diagnostics: ```bash

Run health check

bash diagnostics.sh

Auto-fix common issues

bash mcp-repair.sh ```

---

Development

# Evidence server (watch mode)
cd mcp-evidence-server
npm run dev

# Unified server (watch mode)
cd mcp-unified-consolidated
npm run dev

# MCP Exec (TypeScript compilation)
cd services/mcp-exec
npm run build
npm run dev

---

Deployment

Cloudflare Workers

Unified server can be deployed as a Cloudflare Worker:

# Deploy to production
wrangler deploy

# Monitor logs
wrangler tail chittymcp

# Set secrets
wrangler secret put CHITTY_ID_TOKEN

See wrangler.toml for configuration.

---

Evidence Categories

The Evidence Intake server supports 14 categories:

| Code | Category | Description | |------|----------|-------------| | 00 | KEY_EXHIBITS | High-priority evidence | | 01 | TRO_PROCEEDINGS | TRO proceedings | | 02 | LLC_FORMATION | Corporate documents | | 03 | MEMBERSHIP_REMOVAL | Membership proceedings | | 04 | PREMARITAL_FUNDING | Pre-marital property | | 05 | PROPERTY_TRANSACTIONS | Real estate | | 06 | FINANCIAL_STATEMENTS | Financial docs | | 07 | COURT_FILINGS | Court pleadings | | 08 | ATTORNEY_CORRESPONDENCE | Attorney letters | | 09 | PERJURY_EVIDENCE | Perjury evidence | | 10 | SANCTIONS_RULE137 | Sanctions docs | | 11 | COLOMBIAN_PROPERTY | Colombian property | | 12 | LEASE_AGREEMENTS | Leases | | 98 | DUPLICATES | Duplicate files | | 99 | UNSORTED | Uncategorized |

Files are automatically categorized based on filename patterns.

---

ChittyID Compliance

CRITICAL: All ChittyIDs must be generated via id.chitty.cc API.

• Format: CHITTY-{ENTITY}-{SEQUENCE}-{CHECKSUM}
• Entities: PEO, PLACE, PROP, EVNT, AUTH, INFO, FACT, CONTEXT, ACTOR
• Never generate IDs locally

---

Documentation

• CLAUDE.md - Detailed project overview for Claude Code
• TROUBLESHOOTING.md - Common issues and fixes
• config/chains.json - Chain workflow definitions

---

Architecture

Modular Design

chittymcp/
├── src/
│   ├── core/                    # Shared core utilities
│   │   ├── mcp-server.js       # BaseMCPServer class
│   │   ├── tool-loader.js      # Dynamic tool loading
│   │   ├── chain-executor.js   # Multi-tool workflows
│   │   └── logger.js           # Centralized logging
│   ├── integration/            # ChittyOS service clients
│   │   ├── chittyid-client.js  # ChittyID service
│   │   ├── cloudflare-client.js # Cloudflare API
│   │   └── notion-client.js    # Notion integration
│   ├── tools/                  # Tool modules by domain
│   │   ├── evidence/           # 4 evidence tools
│   │   ├── legal/              # 4 legal tools
│   │   ├── infrastructure/     # 4 infrastructure tools
│   │   └── sync/               # 3 sync tools
│   └── servers/                # Server implementations
│       ├── unified-server.js   # Full consolidated server
│       └── evidence-server.js  # Standalone evidence server
├── config/
│   ├── chains.json             # Workflow chain definitions
│   └── server-config.json      # Server configuration
└── Legacy (backwards compatible):
    ├── mcp-evidence-server/
    └── mcp-unified-consolidated/

Benefits

• Code Reuse: Shared utilities across all servers
• Easy Extension: Add new tools without touching core
• Clean Separation: Tools, integrations, and core separated
• Dynamic Loading: Tools loaded at runtime
• Chain Execution: Complex workflows from simple tools

Adding New Tools

1. Create tool module in src/tools/<category>/:

// src/tools/mycategory/index.js
export const tools = [{
  name: "my_tool",
  description: "What my tool does",
  inputSchema: { /* ... */ }
}];

export { handlers } from "./handlers.js";

// src/tools/mycategory/handlers.js
export const handlers = {
  async my_tool(args) {
    return {
      content: [{
        type: "text",
        text: "Result"
      }]
    };
  }
};

1. Restart server - tools are loaded automatically!

Workflow Chains

Execute multi-tool workflows defined in config/chains.json:

// Execute a chain
await execute_chain({
  chain_name: "legal-workflow",
  parameters: {
    case_type: "civil",
    documents: ["/path/to/filing.pdf"],
    client_id: "CHITTY-PEO-..."
  }
});

Available chains:

• executive-decision - Strategic decision-making workflow
• legal-workflow - Complete legal case management
• infrastructure-deploy - Cloudflare deployment
• cross-sync - Device synchronization
• full-orchestration - All tools combined

Roadmap

v3.0.0 - Completed ✅:

• [x] Modular architecture with core/tools/integration layers
• [x] Dynamic tool loading system
• [x] Chain execution framework
• [x] 15+ tools across 4 domains
• [x] ChittyID integration
• [x] Cloudflare API integration
• [x] Unified and standalone servers

Next (v3.1.0):

• [ ] Executive tool AI integration (Anthropic/OpenAI)
• [ ] ChittyLedger PostgreSQL integration
• [ ] Hot reload for tool modules
• [ ] Web API gateway

Future (v4.0.0):

• [ ] Multi-platform sync (ChatGPT, CustomGPT)
• [ ] Evidence monitoring automation
• [ ] Advanced chain orchestration (rollback, parallel execution)

---

License

MIT License - see LICENSE

---

Support

• Documentation: CLAUDE.md and TROUBLESHOOTING.md
• Issues: https://github.com/chittyos/chittymcp/issues

---

Last Updated: 2025-10-30 Version: 3.0.0 ChittyOS Framework: v1.0.1 MCP SDK: 0.5.0