@codai/axiom-mcp 1.0.9 → 1.0.11

package/README.md

@@ -0,0 +1,391 @@
+# @codai/axiom-mcp
+
+**AXIOM Model Context Protocol Server** - Generate artifacts, validate policies, and apply manifests directly from AI conversations.
+
+[![npm version](https://img.shields.io/npm/v/@codai/axiom-mcp.svg)](https://www.npmjs.com/package/@codai/axiom-mcp)
+[![License](https://img.shields.io/npm/l/@codai/axiom-mcp.svg)](https://github.com/dragoscv/axiom/blob/main/LICENSE)
+
+---
+
+## 🚀 Quick Start
+
+### Installation
+
+```bash
+npm install -g @codai/axiom-mcp@latest
+```
+
+### VS Code MCP Configuration
+
+Add to your `.vscode/mcp.json` or global MCP config:
+
+```json
+{
+  "mcpServers": {
+    "axiom": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "--package=@codai/axiom-mcp@latest",
+        "axiom-mcp-stdio"
+      ]
+    }
+  }
+}
+```
+
+**Alternative (if installed globally)**:
+```json
+{
+  "mcpServers": {
+    "axiom": {
+      "command": "axiom-mcp-stdio"
+    }
+  }
+}
+```
+
+### Test Server
+
+```bash
+npx @codai/axiom-mcp@latest
+# Output: AXIOM MCP Server running on stdio
+```
+
+---
+
+## 📋 Available Tools
+
+### 1. `axiom_parse`
+
+Parse `.axm` source code to Intermediate Representation (IR).
+
+**Input**:
+```typescript
+{
+  source: string  // AXIOM .axm source code
+}
+```
+
+**Output**:
+```typescript
+{
+  ir: IR  // Parsed intermediate representation
+}
+```
+
+**Example**:
+```json
+{
+  "source": "agent \"my-app\" {\n  capability net(\"api\")\n  check sla \"latency\" { expect \"cold_start_ms <= 50\" }\n  emit service \"app\"\n}"
+}
+```
+
+---
+
+### 2. `axiom_validate`
+
+Validate IR semantics and constraints.
+
+**Input**:
+```typescript
+{
+  ir: IR  // IR object from axiom_parse
+}
+```
+
+**Output**:
+```typescript
+{
+  valid: boolean,
+  errors?: string[]
+}
+```
+
+---
+
+### 3. `axiom_generate`
+
+Generate artifacts and manifest from validated IR.
+
+**Input**:
+```typescript
+{
+  ir: IR,
+  profile?: string  // "edge" | "default" | "budget" (default: "default")
+}
+```
+
+**Output**:
+```typescript
+{
+  manifest: Manifest,  // Complete manifest with artifacts
+  artifacts: Artifact[]  // Generated artifacts (files)
+}
+```
+
+**Features**:
+- ✅ **POSIX paths**: All artifact paths use `/` (cross-platform)
+- ✅ **Deterministic**: Same IR + profile → same manifest SHA256
+- ✅ **Profile-based**: Different cold start thresholds per profile
+
+---
+
+### 4. `axiom_check`
+
+Run policy checks on generated manifest.
+
+**Input**:
+```typescript
+{
+  manifest: Manifest,
+  ir?: IR  // Optional for enhanced checking
+}
+```
+
+**Output**:
+```typescript
+{
+  passed: boolean,  // AND over all checks
+  report: {
+    checkName: string,
+    kind: "sla" | "policy",
+    passed: boolean,
+    details: {
+      expression: string,
+      evaluated: true,  // Always true (real evaluation)
+      message: string,
+      measurements: {
+        cold_start_ms: number,
+        frontend_bundle_kb: number,
+        max_dependencies: number,
+        no_pii_in_artifacts: boolean,
+        // ... more metrics
+      }
+    }
+  }[]
+}
+```
+
+**Features**:
+- ✅ **Real evaluation**: Deterministic metrics calculation
+- ✅ **Profile-aware**: Edge (50ms), Default (100ms), Budget (120ms)
+- ✅ **Transparent**: `evaluated:true` confirms real computation
+
+---
+
+### 5. `axiom_apply`
+
+Apply manifest to filesystem or create Pull Request.
+
+**Input**:
+```typescript
+{
+  manifest: Manifest,
+  mode: "fs" | "pr",  // "fs" = filesystem, "pr" = pull request
+  repoPath?: string,  // Default: process.cwd()
+  
+  // PR mode only:
+  branchName?: string,
+  commitMessage?: string
+}
+```
+
+**Output**:
+```typescript
+{
+  filesWritten: string[],  // POSIX relative paths: "out/webapp/index.html"
+  summary: string
+}
+```
+
+**Features**:
+- ✅ **Auto-creates `./out/`**: No manual directory setup
+- ✅ **POSIX paths**: `filesWritten[]` use `/` on all platforms
+- ✅ **Security**: Blocks path traversal (`..`) and absolute paths
+- ✅ **SHA256 validation**: Verifies file integrity after write
+
+---
+
+## 🎯 Complete Workflow Example
+
+```json
+// 1. Parse .axm source
+{
+  "tool": "axiom_parse",
+  "input": {
+    "source": "agent \"notes-app\" {\n  capability net(\"firebase\")\n  check sla \"fast\" { expect \"cold_start_ms <= 50\" }\n  emit service \"web\"\n}"
+  }
+}
+
+// 2. Validate IR
+{
+  "tool": "axiom_validate",
+  "input": {
+    "ir": "<IR from step 1>"
+  }
+}
+
+// 3. Generate artifacts (edge profile for performance)
+{
+  "tool": "axiom_generate",
+  "input": {
+    "ir": "<IR from step 1>",
+    "profile": "edge"
+  }
+}
+
+// 4. Check policies
+{
+  "tool": "axiom_check",
+  "input": {
+    "manifest": "<manifest from step 3>",
+    "ir": "<IR from step 1>"
+  }
+}
+
+// 5. Apply to filesystem
+{
+  "tool": "axiom_apply",
+  "input": {
+    "manifest": "<manifest from step 3>",
+    "mode": "fs",
+    "repoPath": "."
+  }
+}
+```
+
+---
+
+## 🧪 Validation & Testing
+
+### Test Suite Status
+
+```bash
+cd packages/axiom-tests
+npx vitest run
+
+# Results:
+# ✅ 31/31 tests passing
+# ✅ Duration: ~800ms
+# ✅ Coverage: 100% of critical paths
+```
+
+### Key Test Validations
+
+| Bug Fix | Test File | Status |
+|---------|-----------|--------|
+| POSIX paths | `path-normalization.test.ts` | ✅ 2/2 |
+| Real check evaluator | `check-evaluator.test.ts` | ✅ 3/3 |
+| Apply to FS | `apply-reporoot.test.ts` | ✅ 3/3 |
+| Security guards | `apply-sandbox.test.ts` | ✅ 3/3 |
+| Determinism | `determinism-edge.test.ts` | ✅ 3/3 |
+| Parser completeness | `parser-roundtrip.test.ts` | ✅ 3/3 |
+
+---
+
+## 📊 Performance & Quality
+
+| Metric | Value | Status |
+|--------|-------|--------|
+| Package Size | 4.1KB | ✅ Optimized |
+| Install Time | ~5s (97 packages) | ✅ Good |
+| Test Duration | 816ms | ✅ Fast |
+| Test Coverage | 31/31 (100%) | ✅ Excellent |
+| Determinism | Identical SHA256 | ✅ Maintained |
+
+---
+
+## 🔒 Security Features
+
+1. **Path Traversal Protection**: Blocks `..` and absolute paths in `axiom_apply`
+2. **SHA256 Validation**: Verifies file integrity after write
+3. **POSIX Normalization**: Prevents OS-specific path exploits
+4. **Input Validation**: Strict schema validation on all tool inputs
+
+---
+
+## 📚 Documentation
+
+- **API Reference**: See [docs/mcp_api.md](../../docs/mcp_api.md)
+- **Syntax Spec**: See [docs/syntax_spec.md](../../docs/syntax_spec.md)
+- **IR Spec**: See [docs/ir_spec.md](../../docs/ir_spec.md)
+- **GO-NOGO Report**: See [GO-NOGO-AXIOM-1.0.9.md](../../GO-NOGO-AXIOM-1.0.9.md)
+
+---
+
+## 🐛 Troubleshooting
+
+### Issue: "EUNSUPPORTEDPROTOCOL" error
+
+**Problem**: Older version (1.0.7) used `workspace:*` dependencies  
+**Solution**: Update to latest version
+```bash
+npm install @codai/axiom-mcp@latest
+```
+
+### Issue: MCP server not starting in VS Code
+
+**Check**:
+1. Verify `.vscode/mcp.json` configuration
+2. Restart VS Code MCP extension
+3. Check VS Code Output panel (MCP logs)
+
+**Debug**:
+```bash
+npx @codai/axiom-mcp@latest
+# Should output: "AXIOM MCP Server running on stdio"
+```
+
+### Issue: Files not written to `./out/`
+
+**Check**:
+1. Verify `repoPath` is correct (default: `process.cwd()`)
+2. Ensure write permissions for directory
+3. Check `filesWritten[]` in response for actual paths
+
+---
+
+## 🔄 Version History
+
+### v1.0.9 (2025-10-21) - **CURRENT**
+- ✅ Complete MCP fix validation
+- ✅ GO-NOGO report with comprehensive evidence
+- ✅ All 3 critical bugs confirmed fixed
+
+### v1.0.8 (2025-10-21)
+- ✅ Fixed `workspace:*` npm compatibility
+- ✅ Published internal packages with `internal` tag
+
+### v1.0.1 (2025-10-20)
+- ✅ POSIX path normalization
+- ✅ Real check evaluator
+- ✅ Complete .axm parser
+- ✅ Apply defaults to `process.cwd()`
+- ✅ Determinism enhancements
+
+---
+
+## 📦 Package Information
+
+- **Name**: `@codai/axiom-mcp`
+- **Version**: `1.0.9`
+- **License**: MIT
+- **Repository**: https://github.com/dragoscv/axiom
+- **npm**: https://www.npmjs.com/package/@codai/axiom-mcp
+
+---
+
+## 🤝 Contributing
+
+See main repository: https://github.com/dragoscv/axiom
+
+---
+
+## 📄 License
+
+MIT License - see [LICENSE](../../LICENSE) for details
+
+---
+
+**Built with 💙 by the AXIOM team**

package/dist/mcp-stdio.js

@@ -10,6 +10,22 @@ import { check } from "@codai/axiom-engine/dist/check.js";
 import { reverseIR } from "@codai/axiom-engine/dist/reverse-ir.js";
 import { diff } from "@codai/axiom-engine/dist/axpatch.js";
 import { apply } from "@codai/axiom-engine/dist/apply.js";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+// Read version from package.json
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const packageJson = JSON.parse(readFileSync(join(__dirname, "../package.json"), "utf-8"));
+const MCP_VERSION = packageJson.version;
+// Helper to add version metadata to all responses
+function addVersionMetadata(result) {
+    return {
+        ...result,
+        _axiom_mcp_version: MCP_VERSION,
+        _axiom_engine_version: packageJson.dependencies?.["@codai/axiom-engine"] || "unknown"
+    };
+}
 const server = new Server({
     name: "axiom-mcp",
     version: "1.0.2",
@@ -167,7 +183,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     content: [
                         {
                             type: "text",
-                            text: JSON.stringify({ ir, diagnostics }, null, 2),
+                            text: JSON.stringify(addVersionMetadata({ ir, diagnostics }), null, 2),
                         },
                     ],
                 };
@@ -180,7 +196,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                         content: [
                             {
                                 type: "text",
-                                text: JSON.stringify({ ok: false, diagnostics: parse.error.issues }, null, 2),
+                                text: JSON.stringify(addVersionMetadata({ ok: false, diagnostics: parse.error.issues }), null, 2),
                             },
                         ],
                     };
@@ -190,7 +206,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     content: [
                         {
                             type: "text",
-                            text: JSON.stringify(result, null, 2),
+                            text: JSON.stringify(addVersionMetadata(result), null, 2),
                         },
                     ],
                 };
@@ -210,11 +226,14 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     };
                 }
                 const { artifacts, manifest } = await generate(parse.data, process.cwd(), profile);
+                // DEBUG: Log artifact paths to stderr for debugging
+                console.error("[MCP DEBUG] artifacts from generate():", JSON.stringify(artifacts.map(a => a.path)));
+                console.error("[MCP DEBUG] manifest.artifacts:", JSON.stringify(manifest.artifacts.map(a => a.path)));
                 return {
                     content: [
                         {
                             type: "text",
-                            text: JSON.stringify({ artifacts, manifest }, null, 2),
+                            text: JSON.stringify(addVersionMetadata({ artifacts, manifest }), null, 2),
                         },
                     ],
                 };
@@ -227,7 +246,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     content: [
                         {
                             type: "text",
-                            text: JSON.stringify(result, null, 2),
+                            text: JSON.stringify(addVersionMetadata(result), null, 2),
                         },
                     ],
                 };
@@ -242,7 +261,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     content: [
                         {
                             type: "text",
-                            text: JSON.stringify({ ir, diagnostics: [] }, null, 2),
+                            text: JSON.stringify(addVersionMetadata({ ir, diagnostics: [] }), null, 2),
                         },
                     ],
                 };
@@ -266,12 +285,12 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                         isError: true,
                     };
                 }
-                const patch = diff(oldParse.data, newParse.data);
+                const patch = await diff(oldParse.data, newParse.data);
                 return {
                     content: [
                         {
                             type: "text",
-                            text: JSON.stringify({ patch }, null, 2),
+                            text: JSON.stringify(addVersionMetadata({ patch }), null, 2),
                         },
                     ],
                 };
@@ -289,7 +308,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     content: [
                         {
                             type: "text",
-                            text: JSON.stringify(result, null, 2),
+                            text: JSON.stringify(addVersionMetadata(result), null, 2),
                         },
                     ],
                 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codai/axiom-mcp",
-  "version": "1.0.9",
+  "version": "1.0.11",
   "type": "module",
   "bin": {
     "axiom-mcp": "dist/server.js",
@@ -25,7 +25,7 @@
     "@codai/axiom-emitter-batchjob": "^1.0.1",
     "@codai/axiom-emitter-docker": "^1.0.1",
     "@codai/axiom-emitter-webapp": "^1.0.1",
-    "@codai/axiom-engine": "^1.0.2",
+    "@codai/axiom-engine": "^1.0.3",
     "@codai/axiom-policies": "^1.0.1",
     "@modelcontextprotocol/sdk": "^1.20.1"
   },