@cleocode/mcp-server 0.86.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CLEO Development Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,306 @@
+# CLEO MCP Server
+
+**2-gateway CQRS interface for CLEO task management protocol**
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![npm version](https://badge.fury.io/js/%40cleocode%2Fmcp-server.svg)](https://badge.fury.io/js/%40cleocode%2Fmcp-server)
+[![MCP Registry](https://img.shields.io/badge/MCP_Registry-listed-green)](https://registry.modelcontextprotocol.io)
+[![Node.js Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen)](https://nodejs.org/)
+[![MCP Protocol](https://img.shields.io/badge/MCP-1.0.0-blue)](https://modelcontextprotocol.io/)
+
+📚 **[Quick Start](docs/QUICK-START.md)** | **[Usage Guide](docs/USAGE-GUIDE.md)** | **[Workflows](docs/WORKFLOWS.md)** | **[API Docs](docs/INDEX.md)**
+
+## Overview
+
+CLEO MCP Server exposes CLEO's 65 CLI commands and 280+ library functions through two gateway tools using a CQRS (Command Query Responsibility Segregation) pattern:
+
+- **`cleo_query`** - 45 read operations (discovery, status, analysis)
+- **`cleo_mutate`** - 53 write operations (create, update, lifecycle management)
+
+**Token efficiency**: 2 tools (~1,800 tokens) vs 65 tools (~32,500 tokens) = **94% reduction**
+
+## Features
+
+- **Full CLEO Access**: All 98 operations across 8 domains
+- **Protocol Enforcement**: RCSD-IVTR lifecycle with exit codes 60-70
+- **Anti-Hallucination**: 4-layer validation (schema → semantic → referential → protocol)
+- **Safety by Design**: Read operations cannot mutate state
+- **Minimal Token Footprint**: 0.9% of 200K context window
+
+## Installation
+
+```bash
+npm install @cleocode/mcp-server
+```
+
+## Quick Start
+
+### Running the Server
+
+```bash
+# Via npm
+npx cleo-server
+
+# Or directly
+node dist/index.js
+```
+
+### Claude Desktop Configuration
+
+Add to your Claude Desktop config (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "cleo": {
+      "command": "npx",
+      "args": ["-y", "@cleocode/mcp-server"]
+    }
+  }
+}
+```
+
+Or use local installation:
+
+```json
+{
+  "mcpServers": {
+    "cleo": {
+      "command": "node",
+      "args": ["/path/to/cleo-todo/mcp-server/dist/index.js"]
+    }
+  }
+}
+```
+
+## Usage Examples
+
+### Task Management
+
+```typescript
+// Find tasks
+await cleo_query({
+  domain: "tasks",
+  operation: "find",
+  params: { query: "authentication" }
+});
+
+// Create task
+await cleo_mutate({
+  domain: "tasks",
+  operation: "create",
+  params: {
+    title: "Implement authentication",
+    description: "Add JWT-based auth system",
+    priority: 1
+  }
+});
+
+// Complete task
+await cleo_mutate({
+  domain: "tasks",
+  operation: "complete",
+  params: {
+    taskId: "T2405",
+    notes: "Completed successfully"
+  }
+});
+```
+
+### Session Management
+
+```typescript
+// Start session
+await cleo_mutate({
+  domain: "session",
+  operation: "start",
+  params: {
+    scope: "epic:T2400",
+    name: "Feature Development",
+    autoFocus: true
+  }
+});
+
+// Set focus
+await cleo_mutate({
+  domain: "session",
+  operation: "focus.set",
+  params: { taskId: "T2405" }
+});
+```
+
+### Orchestration
+
+```typescript
+// Initialize orchestration
+await cleo_mutate({
+  domain: "orchestrate",
+  operation: "startup",
+  params: { epicId: "T2400" }
+});
+
+// Generate spawn prompt
+await cleo_mutate({
+  domain: "orchestrate",
+  operation: "spawn",
+  params: {
+    taskId: "T2405",
+    skill: "ct-task-executor"
+  }
+});
+```
+
+## Domains
+
+### cleo_query (Read-Only)
+
+- **tasks** - get, list, find, exists, tree, blockers, deps, analyze, next
+- **session** - status, list, show, focus.get, history
+- **orchestrate** - status, next, ready, analyze, context, waves, skill.list
+- **research** - show, list, query, pending, stats, manifest.read
+- **lifecycle** - check, status, history, gates, prerequisites
+- **validate** - schema, protocol, task, manifest, output, compliance.*
+- **system** - version, doctor, config.get, stats, context
+
+### cleo_mutate (Write Operations)
+
+- **tasks** - create, update, complete, delete, archive, unarchive, reparent, promote, reorder, reopen
+- **session** - start, end, resume, suspend, focus.set, focus.clear, gc
+- **orchestrate** - startup, spawn, validate, parallel.*
+- **research** - inject, link, manifest.*
+- **lifecycle** - progress, skip, reset, gate.*
+- **validate** - compliance.record, test.run
+- **release** - prepare, changelog, commit, tag, push, gates.run, rollback
+- **system** - init, config.set, backup, restore, migrate, sync, cleanup
+
+## Configuration
+
+Create `.cleo/config.json` in your project:
+
+```json
+{
+  "mcp": {
+    "enabled": true,
+    "transport": "stdio",
+    "features": {
+      "queryCache": true,
+      "queryCacheTtl": 30000,
+      "auditLog": true,
+      "strictValidation": true
+    }
+  },
+  "lifecycleEnforcement": {
+    "mode": "strict",
+    "allowSkip": ["consensus"]
+  }
+}
+```
+
+## Protocol Enforcement
+
+CLEO enforces the RCSD-IVTR lifecycle pipeline:
+
+```
+Research → Consensus → Specification → Decomposition
+    ↓
+Implementation → Validation → Testing → Release
+```
+
+**Exit codes 60-70** indicate protocol violations:
+
+- 60: Research protocol
+- 61: Consensus protocol
+- 62: Specification protocol
+- 63: Decomposition protocol
+- 64: Implementation protocol
+- 65: Contribution protocol
+- 66: Release protocol
+- 68: Validation protocol
+- 69/70: Testing protocol
+
+## Error Handling
+
+All responses include actionable error information:
+
+```json
+{
+  "success": false,
+  "error": {
+    "code": "E_VALIDATION_FAILED",
+    "exitCode": 6,
+    "message": "Title and description must be different",
+    "fix": "Provide a unique description",
+    "alternatives": [
+      {
+        "action": "Use generated description",
+        "command": "..."
+      }
+    ]
+  }
+}
+```
+
+## Requirements
+
+- **Node.js**: >=18.0.0
+- **CLEO**: v0.70.0+ installed and initialized
+- **Project**: `.cleo/` directory must exist
+
+## Documentation
+
+### Getting Started
+
+- **[Quick Start](docs/QUICK-START.md)** ⚡ - Get started in 5 minutes
+- **[Usage Guide](docs/USAGE-GUIDE.md)** 📖 - Comprehensive guide with examples
+- **[Workflows](docs/WORKFLOWS.md)** 🔄 - Real-world scenario examples
+
+### Complete API Documentation
+
+- **[Documentation Index](docs/INDEX.md)** - Complete documentation navigation
+- **[API Overview](docs/api/overview.md)** - Gateway design and concepts
+- **[Error Codes](docs/api/errors.md)** - Complete error reference
+- **[Protocols](docs/api/protocols.md)** - RCSD-IVTR protocol enforcement
+- **[Examples](docs/examples/task-management.md)** - Complete workflows
+
+### API Reference
+
+- **Gateways**: [cleo_query](docs/api/gateways/cleo_query.md) | [cleo_mutate](docs/api/gateways/cleo_mutate.md)
+- **Domains**: [tasks](docs/api/domains/tasks.md) | [session](docs/api/domains/session.md) | [orchestrate](docs/api/domains/orchestrate.md) | [research](docs/api/domains/research.md) | [lifecycle](docs/api/domains/lifecycle.md) | [validate](docs/api/domains/validate.md) | [release](docs/api/domains/release.md) | [system](docs/api/domains/system.md)
+
+### External Resources
+
+- [Full Specification](https://github.com/cleo-dev/cleo-todo/blob/main/docs/specs/MCP-SERVER-SPECIFICATION.md)
+- [CLEO Documentation](https://github.com/cleo-dev/cleo-todo)
+- [MCP Specification](https://modelcontextprotocol.io/specification)
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Watch mode
+npm run dev
+
+# Test
+npm test
+
+# Lint
+npm run lint
+```
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+## Support
+
+- **Issues**: [GitHub Issues](https://github.com/cleo-dev/cleo-todo/issues)
+- **Documentation**: [CLEO Docs](https://github.com/cleo-dev/cleo-todo/tree/main/docs)
+
+## Credits
+
+Built by the CLEO Development Team for solo developers and AI coding agents.

package/dist/domains/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Domain Handlers Export
+ *
+ * Central export for all domain handlers used by the router
+ *
+ * @task T2911
+ */
+export { TasksHandler } from './tasks.js';
+export { SessionHandler } from './session.js';
+export { OrchestrateHandler } from './orchestrate.js';
+export { ResearchHandler } from './research.js';
+export { LifecycleHandler } from './lifecycle.js';
+export { ValidateHandler } from './validate.js';
+export { ReleaseHandler } from './release.js';
+export { SystemHandler } from './system.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/domains/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/domains/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC"}

package/dist/domains/index.js

@@ -0,0 +1,16 @@
+/**
+ * Domain Handlers Export
+ *
+ * Central export for all domain handlers used by the router
+ *
+ * @task T2911
+ */
+export { TasksHandler } from './tasks.js';
+export { SessionHandler } from './session.js';
+export { OrchestrateHandler } from './orchestrate.js';
+export { ResearchHandler } from './research.js';
+export { LifecycleHandler } from './lifecycle.js';
+export { ValidateHandler } from './validate.js';
+export { ReleaseHandler } from './release.js';
+export { SystemHandler } from './system.js';
+//# sourceMappingURL=index.js.map

package/dist/domains/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/domains/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC"}

package/dist/domains/lifecycle.d.ts

@@ -0,0 +1,147 @@
+/**
+ * Lifecycle Domain Handler
+ *
+ * Implements all 16 lifecycle operations for RCSD-IVTR pipeline:
+ * - Query (9): stages, status, validate, report, export, history, gates, prerequisites, check (alias)
+ * - Mutate (9): record, enforce, skip, unskip, import, reset, gate.pass, gate.fail, progress (alias)
+ *
+ * Handles lifecycle progression, gate enforcement, and RCSD manifest integration.
+ *
+ * @task T2932
+ */
+import { DomainHandler, DomainResponse } from '../lib/router.js';
+import { CLIExecutor } from '../lib/executor.js';
+/**
+ * Lifecycle stages in RCSD-IVTR pipeline
+ */
+export type LifecycleStage = 'research' | 'consensus' | 'specification' | 'decomposition' | 'implementation' | 'validation' | 'testing' | 'release' | 'contribution';
+/**
+ * Stage status
+ */
+export type StageStatus = 'pending' | 'completed' | 'skipped' | 'blocked';
+/**
+ * Lifecycle stage info
+ */
+export interface StageInfo {
+    stage: LifecycleStage;
+    name: string;
+    description: string;
+    exitCode: number;
+    order: number;
+    optional: boolean;
+}
+/**
+ * Lifecycle domain handler implementation
+ */
+export declare class LifecycleHandler implements DomainHandler {
+    private executor;
+    constructor(executor: CLIExecutor);
+    /**
+     * Query operations (read-only)
+     */
+    query(operation: string, params?: Record<string, unknown>): Promise<DomainResponse>;
+    /**
+     * Mutate operations (write)
+     */
+    mutate(operation: string, params?: Record<string, unknown>): Promise<DomainResponse>;
+    /**
+     * Get supported operations
+     */
+    getSupportedOperations(): {
+        query: string[];
+        mutate: string[];
+    };
+    /**
+     * stages - List lifecycle stages
+     * CLI: cleo lifecycle stages [--pipeline <rcsd|ivtr|all>]
+     */
+    private queryStages;
+    /**
+     * status - Get lifecycle status for epic
+     * CLI: cleo lifecycle status <epicId>
+     */
+    private queryStatus;
+    /**
+     * validate - Validate lifecycle progression
+     * CLI: cleo lifecycle validate <epicId> <targetStage>
+     */
+    private queryValidate;
+    /**
+     * report - Generate lifecycle report
+     * CLI: cleo lifecycle report [--epic <id>] [--format <summary|detailed>]
+     */
+    private queryReport;
+    /**
+     * export - Export lifecycle data
+     * CLI: cleo lifecycle export [--epic <id>] [--format <json|csv>] [--history]
+     */
+    private queryExport;
+    /**
+     * record - Record stage completion
+     * CLI: cleo lifecycle record <epicId> <stage> <status> [--notes <n>]
+     */
+    private mutateRecord;
+    /**
+     * enforce - Enforce lifecycle gates
+     * CLI: cleo lifecycle enforce <epicId> <stage> [--strict]
+     */
+    private mutateEnforce;
+    /**
+     * skip - Skip a stage
+     * CLI: cleo lifecycle skip <epicId> <stage> --reason <reason>
+     */
+    private mutateSkip;
+    /**
+     * unskip - Unskip a stage
+     * CLI: cleo lifecycle unskip <epicId> <stage>
+     */
+    private mutateUnskip;
+    /**
+     * import - Import lifecycle data
+     * CLI: cleo lifecycle import <source> [--epic <id>] [--overwrite]
+     */
+    private mutateImport;
+    /**
+     * history - Stage transition history
+     * CLI: cleo lifecycle history <taskId>
+     */
+    private queryHistory;
+    /**
+     * gates - All gate statuses
+     * CLI: cleo lifecycle gates <taskId>
+     */
+    private queryGates;
+    /**
+     * prerequisites - Required prior stages
+     * CLI: cleo lifecycle prerequisites <targetStage>
+     */
+    private queryPrerequisites;
+    /**
+     * reset - Reset a stage (emergency)
+     * CLI: cleo lifecycle reset <taskId> <stage> --reason <reason>
+     */
+    private mutateReset;
+    /**
+     * gate.pass - Mark gate as passed
+     * CLI: cleo lifecycle gate pass <taskId> <gateName> --agent <agent> [--notes <notes>]
+     */
+    private mutateGatePass;
+    /**
+     * gate.fail - Mark gate as failed
+     * CLI: cleo lifecycle gate fail <taskId> <gateName> --reason <reason>
+     */
+    private mutateGateFail;
+    /**
+     * Wrap executor result in DomainResponse format
+     */
+    private wrapExecutorResult;
+    /**
+     * Create error response
+     */
+    private createErrorResponse;
+    /**
+     * Handle unexpected errors
+     */
+    private handleError;
+}
+//# sourceMappingURL=lifecycle.d.ts.map

package/dist/domains/lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.d.ts","sourceRoot":"","sources":["../../src/domains/lifecycle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACjE,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEjD;;GAEG;AACH,MAAM,MAAM,cAAc,GACtB,UAAU,GACV,WAAW,GACX,eAAe,GACf,eAAe,GACf,gBAAgB,GAChB,YAAY,GACZ,SAAS,GACT,SAAS,GACT,cAAc,CAAC;AAEnB;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,WAAW,GAAG,SAAS,GAAG,SAAS,CAAC;AAE1E;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,cAAc,CAAC;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,OAAO,CAAC;CACnB;AAqPD;;GAEG;AACH,qBAAa,gBAAiB,YAAW,aAAa;IACxC,OAAO,CAAC,QAAQ;gBAAR,QAAQ,EAAE,WAAW;IAEzC;;OAEG;IACG,KAAK,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,cAAc,CAAC;IAsCzF;;OAEG;IACG,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,cAAc,CAAC;IAsC1F;;OAEG;IACH,sBAAsB,IAAI;QAAE,KAAK,EAAE,MAAM,EAAE,CAAC;QAAC,MAAM,EAAE,MAAM,EAAE,CAAA;KAAE;IAS/D;;;OAGG;YACW,WAAW;IAezB;;;OAGG;YACW,WAAW;IAwBzB;;;OAGG;YACW,aAAa;IAwB3B;;;OAGG;YACW,WAAW;IAgBzB;;;OAGG;YACW,WAAW;IAmBzB;;;OAGG;YACW,YAAY;IA2B1B;;;OAGG;YACW,aAAa;IA2B3B;;;OAGG;YACW,UAAU;IAwBxB;;;OAGG;YACW,YAAY;IAwB1B;;;OAGG;YACW,YAAY;IA4B1B;;;OAGG;YACW,YAAY;IAwB1B;;;OAGG;YACW,UAAU;IAwBxB;;;OAGG;YACW,kBAAkB;IA0BhC;;;OAGG;YACW,WAAW;IAwBzB;;;OAGG;YACW,cAAc;IA4B5B;;;OAGG;YACW,cAAc;IA6B5B;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAsC1B;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAyB3B;;OAEG;IACH,OAAO,CAAC,WAAW;CAgBpB"}