mcp-cognition-engine 1.0.0-alpha.1

package/docs/community/feedback-playbook.md

@@ -0,0 +1,94 @@
+# Community Feedback Playbook
+
+Prepared responses for the top 5 frequently asked questions about licensing and trademark policy.
+
+---
+
+## Q1: Can I use this in my commercial product?
+
+**Scenario:** Enterprise developer asking about embedding the engine in a proprietary SaaS product.
+
+**Answer Template:**
+
+> Yes, you absolutely can. The Apache 2.0 License (Section 2) grants you a perpetual, worldwide, non-exclusive, royalty-free license to use, modify, and distribute the software in any context — including commercial products.
+>
+> The trademark policy in `TRADEMARK.md` only restricts the use of the "Cognition Graph" brand name and logo in your product naming or marketing. Using the underlying code in your commercial product has no trademark implications as long as you do not misrepresent affiliation.
+>
+> For reference: *Section 2 of Apache 2.0 (Grant of Copyright License)* and *Section 6 (Trademarks)* explicitly separate software rights from trademark rights.
+
+---
+
+## Q2: Can I modify and redistribute the code?
+
+**Scenario:** Contributor wanting to fork and republish.
+
+**Answer Template:**
+
+> Yes, Apache 2.0 (Section 4) permits you to reproduce, prepare derivative works, and distribute copies. You may add your own copyright statement to your modifications and may offer different license terms for your modifications — but the original work must remain under Apache 2.0.
+>
+> Key requirements:
+> - Retain all original copyright, patent, trademark, and attribution notices.
+> - Include a conspicuous notice that your version includes modifications.
+> - If you include the "NOTICE" file (if any), do not modify it.
+
+---
+
+## Q3: How do I report a trademark violation?
+
+**Scenario:** Someone is using "Cognition Graph" in a way that implies endorsement without permission.
+
+**Answer Template:**
+
+> Thank you for helping protect the project. Please:
+>
+> 1. Gather evidence: screenshot, URL, and a description of how the mark is being used.
+> 2. Open a private report via email: **wind-come@qq.com**
+> 3. Alternatively, open a GitHub Discussion in the "Q&A" category with a private note flag.
+>
+> We review reports within 5 business days. If a violation is confirmed, we will:
+> - Issue a cease-and-desist notice to the infringing party.
+> - Document the resolution in the project records (without exposing reporter identity).
+>
+> We reserve the right to escalate under applicable trademark law.
+
+---
+
+## Q4: Do I need to sign a CLA to contribute?
+
+**Scenario:** New contributor asking about legal paperwork before submitting a PR.
+
+**Answer Template:**
+
+> No, you do not need to sign a separate Contributor License Agreement (CLA). Apache 2.0 (Section 5, Submission of Contributions) handles this automatically:
+>
+> *"Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions."*
+>
+> This means:
+> - By submitting a PR, you agree that your contribution is licensed under Apache 2.0.
+> - You retain copyright over your contributions.
+> - No additional CLA or legal agreement is required.
+>
+> If your organization requires a signed agreement for legal compliance, contact us at wind-come@qq.com to arrange a corporate CLA.
+
+---
+
+## Q5: What if my company requires GPL compatibility?
+
+**Scenario:** Organization using GPL-licensed tools wanting to integrate this project.
+
+**Answer Template:**
+
+> Apache 2.0 is a permissive license and is compatible with GPLv3 (but not GPLv2). Specifically:
+>
+> - **Apache 2.0 → GPLv3:** Compatible. You can combine Apache 2.0 code with GPLv3 code.
+> - **Apache 2.0 → GPLv2:** Not directly compatible. You cannot distribute Apache 2.0 code under GPLv2 alone.
+>
+> If your project is GPLv2-only, you have two options:
+> 1. Keep the Apache 2.0 components as separate processes communicating via IPC/network (not derivative works).
+> 2. Contact us at wind-come@qq.com to discuss alternative licensing arrangements.
+>
+> The core engines (cognition graph, MCP tools) will always remain Apache 2.0, but we are open to discussing dual-licensing for enterprise integration scenarios.
+
+---
+
+*Last updated: 2026-06-15*

package/docs/integration-snippets.md

@@ -0,0 +1,100 @@
+# MCP Integration Snippets
+
+Ready-to-copy JSON configuration snippets for all major MCP clients.
+
+## Cursor
+
+Add to `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "cognition-engine": {
+      "command": "npx",
+      "args": ["-y", "mcp-cognition-engine@latest"],
+      "env": {
+        "COGNITION_DB_PATH": "~/.cognition/dev.db"
+      }
+    }
+  }
+}
+```
+
+After adding, open Cursor → Settings → MCP and click **Test Connection**.
+
+## Claude Desktop
+
+Add to `claude_desktop_config.json` (or `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
+
+```json
+{
+  "mcpServers": {
+    "cognition-engine": {
+      "command": "npx",
+      "args": ["-y", "mcp-cognition-engine@latest"],
+      "env": {
+        "COGNITION_DB_PATH": "~/.cognition/dev.db"
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop. The cognition engine tools should appear in the MCP tool list.
+
+## VS Code (GitHub Copilot Chat / MCP Extension)
+
+Add to `.vscode/mcp.json` or User `settings.json`:
+
+```json
+{
+  "mcp": {
+    "servers": {
+      "cognition-engine": {
+        "type": "stdio",
+        "command": "npx",
+        "args": ["-y", "mcp-cognition-engine@latest"],
+        "env": {
+          "COGNITION_DB_PATH": "~/.cognition/dev.db"
+        }
+      }
+    }
+  }
+}
+```
+
+Open VS Code Command Palette → 'MCP: Restart Servers'.
+
+## Local Development (from source)
+
+If you cloned the repo and want to run locally:
+
+```json
+{
+  "mcpServers": {
+    "cognition-engine": {
+      "command": "node",
+      "args": ["dist/cli.js"],
+      "env": {
+        "COGNITION_DB_PATH": "./prisma/dev.db"
+      }
+    }
+  }
+}
+```
+
+---
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `COGNITION_DB_PATH` | `~/.cognition/dev.db` | Path to the SQLite database file. Created automatically if missing. |
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---------|-----|
+| "Database not found" | Delete the DB file and restart — it will auto-initialize. |
+| Connection timeout | Make sure `prisma` is available in `npx` cache. First run may take 30s for npm install. |
+| Tool not appearing | Check MCP client logs for parse errors. Verify the JSON snippet syntax. |

package/docs/mcp-integration-guide.md

@@ -0,0 +1,151 @@
+# MCP Production-Grade Integration Guide
+
+> For: Cursor, Claude Desktop, Cline / Roo Code
+> Last updated: 2026-06-15
+
+---
+
+## 1. Quick Start
+
+### Prerequisites
+- Node.js >= 18
+- npm >= 9
+
+### Start the Server
+
+```bash
+# stdio mode (default for Cursor / Claude Desktop)
+npm run build && node dist/index.js
+
+# HTTP mode (for Cline / Roo Code remote agents)
+TRANSPORT=http PORT=3000 npm run build && node dist/index.js
+```
+
+---
+
+## 2. Agent Configuration
+
+### Cursor
+
+Add to `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "cognition-engine": {
+      "command": "node",
+      "args": ["dist/index.js"],
+      "env": {
+        "DATABASE_URL": "file:./dev.db"
+      }
+    }
+  }
+}
+```
+
+Restart Cursor. Check Settings > MCP for green status indicator.
+
+### Claude Desktop
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "cognition-engine": {
+      "command": "node",
+      "args": ["path/to/mcp-rule-engine/dist/index.js"],
+      "env": {
+        "DATABASE_URL": "file:./dev.db"
+      }
+    }
+  }
+}
+```
+
+### Cline / Roo Code (HTTP)
+
+```json
+{
+  "mcpServers": {
+    "cognition-engine": {
+      "url": "http://localhost:3000",
+      "transport": "streamable-http"
+    }
+  }
+}
+```
+
+---
+
+## 3. Tool Reference
+
+### cognition_query
+
+Query the cognition graph by context hash. Returns relevant nodes sorted by relevance.
+
+```json
+{
+  "contextHash": "abc123",
+  "intentHint": "BUGFIX",
+  "maxDepth": 3
+}
+```
+
+### cognition_validate
+
+Validate code against an AST template.
+
+```json
+{
+  "nodeId": "node-123",
+  "targetFileContent": "function foo() { return 1; }"
+}
+```
+
+### cognition_feedback
+
+Provide feedback to refine future queries.
+
+```json
+{
+  "nodeId": "node-123",
+  "edgeId": "edge-456",
+  "outcome": "ACCEPTED",
+  "comment": "Useful constraint"
+}
+```
+
+---
+
+## 4. Resources
+
+| URI | Type | Content |
+|-----|------|---------|
+| `cognition://schema` | application/json | Data model schema |
+| `cognition://stats` | application/json | Graph statistics |
+| `cognition://docs` | text/markdown | Full documentation |
+
+---
+
+## 5. Error Handling
+
+| Code | Meaning | Retryable |
+|------|---------|-----------|
+| `-32602` | Invalid parameters | false |
+| `-32603` | Internal engine error | true |
+| `-32001` | Traversal timeout | true |
+
+All error responses include a `retryable` boolean field.
+
+---
+
+## 6. Troubleshooting
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| Tool list not loading | Missing environment variables | Set `DATABASE_URL` |
+| Server exits immediately | Prisma client not generated | Run `npx prisma generate` |
+| HTTP connection refused | Wrong port | Check `PORT` env var and firewall |
+| "Tool not found" | SDK version mismatch | Use @modelcontextprotocol/sdk >= 1.0 |
+| Resource returns empty | Database not migrated | Run `npx prisma migrate deploy` |

package/docs/phase4-mcp-feedback.md

@@ -0,0 +1,155 @@
+# Phase 4 — MCP 工具与反馈闭环设计文档
+
+> **日期:** 2026-06-15
+> **项目:** MCP Rule Engine → Cognition Engine Refactoring
+
+---
+
+## 1. 新增 MCP Tools
+
+三个新工具注册在 MCP Server 的 `ListToolsRequestSchema` 中，与 Legacy Engine 的 6 个工具完全独立、共存。
+
+### 1.1 cognition_query
+
+| 属性 | 值 |
+|------|-----|
+| 名称 | `cognition_query` |
+| 描述 | 主动查询认知图谱并召回关联认知节点 |
+| 输入 | `contextHash` (string, required), `intentHint` (string enum, optional), `maxDepth` (number, optional) |
+| 输出 | `{ nodes: [{id, type, abstractionLevel, relevanceScore}], traversalMs, truncated }` |
+
+**内部逻辑:**
+1. 使用 `contextHash` 直接匹配认知图谱节点（跳过 hash 计算）
+2. 若提供 `intentHint`，则作为遍历偏置传入 GraphTraverser
+3. 加权 BFS 遍历子图，返回排序后的节点摘要
+4. **异步（fire-and-forget）** 记录 PENDING 反馈事件
+
+### 1.2 cognition_validate
+
+| 属性 | 值 |
+|------|-----|
+| 名称 | `cognition_validate` |
+| 描述 | 对文件内容执行 AST 级约束校验 |
+| 输入 | `nodeId` (string, required), `targetFileContent` (string, required) |
+| 输出 | `{ valid: boolean, violations: [{constraintPath, expected, actual}], transformPatch? }` |
+
+**内部逻辑:**
+1. 根据 `nodeId` 查找 CognitionNode
+2. 获取关联的 AstTemplate.templateDsl
+3. 调用 `solveConstraints()` 对目标文件内容执行 AST 约束求解
+4. 返回校验结果
+
+### 1.3 cognition_feedback
+
+| 属性 | 值 |
+|------|-----|
+| 名称 | `cognition_feedback` |
+| 描述 | 接收 Agent 执行结果反馈，更新节点权重与边强度 |
+| 输入 | `nodeId` (required), `edgeId` (optional), `outcome` (ACCEPTED/REJECTED/MODIFIED, required), `comment` (optional) |
+| 输出 | `{ updatedWeight: number|null, feedbackId: string }` |
+
+**内部逻辑:**
+1. 根据 `outcome` 计算权重增量：ACCEPTED=+0.1, REJECTED=-0.2, MODIFIED=+0.05
+2. 若提供 `edgeId`，调用 updateEdgeWeight() 调整边权重
+3. 调用 `recordFeedbackEvent()` 记录反馈事件
+4. 调用 `resolveFeedbackEvent()` 更新事件状态
+
+---
+
+## 2. 反馈闭环机制
+
+### 2.1 数据流
+
+```
+cognition_query ---> recordFeedbackEvent(PENDING)
+       |
+       v
+  Agent 处理结果
+       |
+       v
+cognition_feedback ---> resolveFeedbackEvent(RESOLVED)
+                        |--- outcome=ACCEPTED/REJECTED/MODIFIED
+                        v
+                  updateEdgeWeight(delta)
+                        |
+                        v （下一次查询）
+                  cognition_query 使用更新后的权重
+```
+
+### 2.2 事件存储
+
+使用现有的 `MetricEvent` 表（不新增 Prisma Model）:
+- `eventType`: `"cognition_feedback_pending"` (初始)
+- `properties`: JSON 字符串，包含 `{nodeId, edgeId, outcome, status, comment}`
+
+### 2.3 异步非阻塞保证
+
+- `recordFeedbackEvent()` 在 query/validate 响应发送后调用
+- 调用方式为 `repo.recordFeedbackEvent(...).catch(() => {})`
+- 不阻塞主工具响应路径
+
+---
+
+## 3. 向后兼容性
+
+| 方面 | 保证 |
+|------|------|
+| Legacy 工具 | 6 个原始工具完全不变 |
+| 工具注册 | 新工具追加在原有数组末尾 |
+| Switch 路由 | 新 case 加在 default 前 |
+| Import | 新文件 `cognition-tools.ts` 物理隔离 |
+
+---
+
+## 4. 测试覆盖
+
+| 测试套件 | 测试数 | 说明 |
+|---------|-------|------|
+| cognition_query | 2 | 错误输入 + 正常路径 |
+| cognition_validate | 3 | 缺失字段 + 节点不存在 |
+| cognition_feedback | 4 | 错误输入 + 三种 outcome |
+| 原有测试 | 85 | 无回归 |
+| **总计** | **94+** | |
+
+---
+
+## 5. Tool Schema 定义
+
+### cognition_query
+```json
+{
+  "type": "object",
+  "properties": {
+    "contextHash": { "type": "string" },
+    "intentHint": { "type": "string", "enum": ["REFACTOR", "BUGFIX", "BOILERPLATE"] },
+    "maxDepth": { "type": "number" }
+  },
+  "required": ["contextHash"]
+}
+```
+
+### cognition_validate
+```json
+{
+  "type": "object",
+  "properties": {
+    "nodeId": { "type": "string" },
+    "targetFileContent": { "type": "string" }
+  },
+  "required": ["nodeId", "targetFileContent"]
+}
+```
+
+### cognition_feedback
+```json
+{
+  "type": "object",
+  "properties": {
+    "nodeId": { "type": "string" },
+    "edgeId": { "type": "string" },
+    "outcome": { "type": "string", "enum": ["ACCEPTED", "REJECTED", "MODIFIED"] },
+    "comment": { "type": "string" }
+  },
+  "required": ["nodeId", "outcome"]
+}
+```

package/docs/trust-governance-protocol.md

@@ -0,0 +1,72 @@
+# Trust Governance Protocol
+
+## Overview
+
+The trust governance layer provides hard constraints, auditable injection approval, and dynamic configuration for AI agents using the MCP Rule Engine. It enforces that all code generation is validated before output, and all rule modifications are explicitly approved by a human operator.
+
+## Three-Tier Knowledge Base
+
+| Tier | Scope | Storage | Validation Mode |
+|------|-------|---------|-----------------|
+| Global | Universal code patterns across all projects | CognitionNode(type=CONSTRAINT) with NegativeConstraint payload | REJECT (hard block) |
+| Project | Project-specific conventions and rules | CognitionNode(type=CONSTRAINT) | WARN (soft warning) |
+| Reuse | Cross-project patterns and heuristics | CognitionNode(type=INTENT or HEURISTIC) | Weight-based via traversal |
+
+## Injection Approval Flow
+
+All rule modifications follow this protocol:
+
+1. Agent calls cognition_query, which implicitly creates a Proposal with TTL=5 minutes
+2. User receives the proposal via cognition_query output
+3. User calls cognition_approve_injection(proposalId, decision)
+4. Decision is recorded in the audit log
+5. If approved, the traversal or validation proceeds
+6. If expired (TTL exceeded), returns -32602 with retryable:true
+
+### TTL and Conflict Rules
+
+- TTL = 5 minutes from proposal creation
+- Only one active proposal per contextHash
+- Duplicate proposals return the existing proposal
+- Expired proposals can be retried
+
+## Constraint Validation Dual-Mode
+
+- **REJECT (Hard Block)**: The constraint violation is returned as error code -32602 with the ruleId. The agent MUST NOT proceed with the current operation.
+- **WARN (Soft Warning)**: The violation is returned as part of the output. The agent may proceed with user confirmation.
+
+## Config Hot Update
+
+Dynamic thresholds (e.g., similarity 0.7/0.9) are stored as CognitionNode(type=HEURISTIC):
+
+1. Agent calls cognition_update_config(key, value, expertMode=true)
+2. A new config node is created with the updated value
+3. The old node receives a supersededBy metadata field pointing to the new node
+4. Non-expert mode calls return -32601 Unauthorized
+
+## Audit Logging
+
+All governance events are recorded using the MetricEvent table:
+
+- eventType: cognition_feedback_pending, proposal_created, proposal_approved, proposal_rejected, proposal_expired
+- Properties: JSON with all relevant context data
+- Written asynchronously (fire-and-forget)
+- On write failure, events fall back to logs/fallback.log
+
+## Error Codes
+
+| Code | Meaning | Retryable | Scenario |
+|------|---------|-----------|----------|
+| -32602 | Invalid Request | false | Missing required fields, invalid parameters |
+| -32602 | Proposal Expired | true | TTL exceeded |
+| -32602 | Unauthorized Injection | false | Non-expert mode config attempt |
+| -32603 | Internal Error | true | Engine failure during validation or traversal |
+| -32001 | Timeout | true | Graph traversal exceeded time limit |
+
+## Response Validation Middleware
+
+All tools/call responses are validated for Schema compliance:
+
+- If validationRequired is missing from cognition_query or cognition_validate responses, the middleware auto-adds it with value true
+- A WARN log entry is written to logs/validation-warnings.log
+- This ensures Agent constraint even if the Agent ignores the Schema declaration

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "mcp-cognition-engine",
+  "version": "1.0.0-alpha.1",
+  "description": "MCP Server for Cognition Engine & Trust Governance Layer — weighted graph traversal, AST constraint solving, and auditable injection approval for AI agents.",
+  "type": "module",
+  "main": "dist/index.js",
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsx watch src/index.ts",
+    "db:generate": "prisma generate",
+    "db:push": "prisma db push",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "license:check": "node scripts/check-license.js",
+    "license:fix": "node scripts/check-license.js",
+    "bench": "npx tsx benchmarks/intent-recognizer.bench.ts && npx tsx benchmarks/graph-traverser.bench.ts"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@prisma/client": "^5.22.0",
+    "better-sqlite3": "^12.10.1",
+    "tree-sitter": "^0.21.1",
+    "tree-sitter-javascript": "^0.25.0",
+    "tree-sitter-python": "^0.25.0",
+    "tree-sitter-typescript": "^0.23.2",
+    "web-tree-sitter": "^0.26.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "prisma": "^5.22.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  },
+  "author": "MCP Rule Engine Contributors",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sole03/mcp-rule-engine.git"
+  },
+  "bugs": {
+    "url": "https://github.com/sole03/mcp-rule-engine/issues"
+  },
+  "homepage": "https://github.com/sole03/mcp-rule-engine#readme",
+  "bin": {
+    "mcp-cognition-engine": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "prisma/schema.prisma",
+    "README.md",
+    "docs/"
+  ],
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "cognition",
+    "graph",
+    "ast",
+    "ai-agent"
+  ],
+  "license": "Apache-2.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "prisma": "^5.22.0"
+  },
+  "peerDependenciesMeta": {
+    "prisma": {
+      "optional": true
+    }
+  }
+}