@agent-lint/mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Agent Lint Contributors
+
+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,134 @@
+# @agent-lint/mcp
+
+MCP server for AI agent context artifact analysis and quality scoring.
+
+**Zero LLM dependencies.** Fully deterministic. Local-first. No database. No auth.
+
+## What It Does
+
+Provides a [Model Context Protocol](https://modelcontextprotocol.io/) server that evaluates AI-agent context artifacts:
+
+- `AGENTS.md` / `CLAUDE.md`
+- Skills, Rules, Workflows, Plans
+
+Reproducible quality scoring across **12 metrics**, evidence-backed assessment, guardrail checks, and repeatable improvement loops — all without calling any LLM.
+
+## Quick Start
+
+```bash
+npx -y @agent-lint/mcp
+```
+
+## MCP Client Configuration
+
+### Cursor
+
+Add to `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "agent-lint": {
+      "command": "npx",
+      "args": ["-y", "@agent-lint/mcp"]
+    }
+  }
+}
+```
+
+### Claude Desktop
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "agent-lint": {
+      "command": "npx",
+      "args": ["-y", "@agent-lint/mcp"]
+    }
+  }
+}
+```
+
+### VS Code
+
+Add to your VS Code `settings.json`:
+
+```json
+{
+  "mcp": {
+    "servers": {
+      "agent-lint": {
+        "command": "npx",
+        "args": ["-y", "@agent-lint/mcp"]
+      }
+    }
+  }
+}
+```
+
+### Windsurf
+
+Add to your Windsurf MCP config:
+
+```json
+{
+  "mcpServers": {
+    "agent-lint": {
+      "command": "npx",
+      "args": ["-y", "@agent-lint/mcp"]
+    }
+  }
+}
+```
+
+## Available Tools
+
+| Tool                           | Description                                                                          |
+| ------------------------------ | ------------------------------------------------------------------------------------ |
+| `analyze_artifact`             | Analyze a single artifact — returns scores across 12 metrics with findings and hints |
+| `analyze_workspace_artifacts`  | Scan a workspace directory for AI agent artifacts with framework detection           |
+| `analyze_context_bundle`       | Analyze multiple artifacts together for cross-artifact consistency                   |
+| `prepare_artifact_fix_context` | Prepare context for an artifact improvement loop                                     |
+| `submit_client_assessment`     | Submit a client LLM assessment with evidence-backed scores                           |
+| `quality_gate_artifact`        | Check if an artifact meets a target quality score                                    |
+| `suggest_patch`                | Generate patch suggestions to improve an artifact                                    |
+| `apply_patches`                | Apply patches to local files with hash guard, allowlist, and backup protection       |
+| `validate_export`              | Validate final artifact output for safety and correctness                            |
+
+## Quality Metrics (12)
+
+`clarity` · `specificity` · `scope-control` · `completeness` · `actionability` · `verifiability` · `safety` · `injection-resistance` · `secret-hygiene` · `token-efficiency` · `platform-fit` · `maintainability`
+
+## Programmatic Usage
+
+```typescript
+import { createAgentLintMcpServer } from "@agent-lint/mcp";
+
+const server = createAgentLintMcpServer({
+  transportMode: "stdio",
+});
+```
+
+## HTTP Transport
+
+```bash
+npx @agent-lint/mcp --http --port 3001
+```
+
+## Design Principles
+
+- **No LLM**: Fully deterministic. No API calls, no tokens, no cost.
+- **No State**: Every call is stateless. No database, no cache.
+- **No File Writes**: Read-only by default. `apply_patches` requires explicit flags + hash guard.
+- **Minimum Dependencies**: Published package under 500 KB packed.
+
+## Related
+
+- [`@agent-lint/cli`](https://www.npmjs.com/package/@agent-lint/cli) — CLI interface
+- [Repository](https://gitlab.com/bsamilozturk/agentlint)
+
+## License
+
+MIT

package/dist/bin.js

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+import {
+  logMcp,
+  runHttpServer,
+  runStdioServer
+} from "./chunk-FHXMDRDX.js";
+
+// src/bin.ts
+var nodeVersion = parseInt(process.versions.node.split(".")[0], 10);
+if (nodeVersion < 18) {
+  process.stderr.write(
+    `agent-lint requires Node.js >= 18. Current: ${process.versions.node}
+`
+  );
+  process.exit(1);
+}
+var args = process.argv.slice(2);
+function hasFlag(name) {
+  return args.includes(`--${name}`);
+}
+function getFlagValue(name) {
+  const idx = args.indexOf(`--${name}`);
+  if (idx >= 0 && idx + 1 < args.length) {
+    return args[idx + 1];
+  }
+  return void 0;
+}
+if (hasFlag("help") || hasFlag("h")) {
+  process.stderr.write([
+    "Usage: agent-lint-mcp [options]",
+    "",
+    "Options:",
+    "  --http         Start HTTP transport (StreamableHTTP) instead of stdio",
+    "  --port <n>     HTTP port (default: 3001, or MCP_HTTP_PORT env var)",
+    "  --host <addr>  HTTP bind address (default: 127.0.0.1)",
+    "  --help, -h     Show this help message",
+    ""
+  ].join("\n"));
+  process.exit(0);
+}
+if (hasFlag("http")) {
+  const port = getFlagValue("port") ? parseInt(getFlagValue("port"), 10) : void 0;
+  const hostname = getFlagValue("host") ?? void 0;
+  runHttpServer({ port, hostname }).catch((error) => {
+    logMcp("error", "mcp.http.fatal", {
+      error: error instanceof Error ? error.message : "Unknown error"
+    });
+    process.exit(1);
+  });
+} else {
+  runStdioServer().catch((error) => {
+    logMcp("error", "mcp.stdio.fatal", {
+      error: error instanceof Error ? error.message : "Unknown error"
+    });
+    process.exit(1);
+  });
+}
+//# sourceMappingURL=bin.js.map

package/dist/bin.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/bin.ts"],"sourcesContent":["#!/usr/bin/env node\nconst nodeVersion = parseInt(process.versions.node.split(\".\")[0], 10);\nif (nodeVersion < 18) {\n  process.stderr.write(\n    `agent-lint requires Node.js >= 18. Current: ${process.versions.node}\\n`\n  );\n  process.exit(1);\n}\n\nimport { runStdioServer } from \"./stdio.js\";\nimport { runHttpServer } from \"./http.js\";\nimport { logMcp } from \"./logger.js\";\n\n// ---------------------------------------------------------------------------\n// CLI argument parsing (no new deps — simple process.argv)\n// ---------------------------------------------------------------------------\n\nconst args = process.argv.slice(2);\n\nfunction hasFlag(name: string): boolean {\n  return args.includes(`--${name}`);\n}\n\nfunction getFlagValue(name: string): string | undefined {\n  const idx = args.indexOf(`--${name}`);\n  if (idx >= 0 && idx + 1 < args.length) {\n    return args[idx + 1];\n  }\n  return undefined;\n}\n\nif (hasFlag(\"help\") || hasFlag(\"h\")) {\n  process.stderr.write([\n    \"Usage: agent-lint-mcp [options]\",\n    \"\",\n    \"Options:\",\n    \"  --http         Start HTTP transport (StreamableHTTP) instead of stdio\",\n    \"  --port <n>     HTTP port (default: 3001, or MCP_HTTP_PORT env var)\",\n    \"  --host <addr>  HTTP bind address (default: 127.0.0.1)\",\n    \"  --help, -h     Show this help message\",\n    \"\",\n  ].join(\"\\n\"));\n  process.exit(0);\n}\n\n// ---------------------------------------------------------------------------\n// Transport selection\n// ---------------------------------------------------------------------------\n\nif (hasFlag(\"http\")) {\n  const port = getFlagValue(\"port\") ? parseInt(getFlagValue(\"port\")!, 10) : undefined;\n  const hostname = getFlagValue(\"host\") ?? undefined;\n\n  runHttpServer({ port, hostname }).catch((error) => {\n    logMcp(\"error\", \"mcp.http.fatal\", {\n      error: error instanceof Error ? error.message : \"Unknown error\",\n    });\n    process.exit(1);\n  });\n} else {\n  runStdioServer().catch((error) => {\n    logMcp(\"error\", \"mcp.stdio.fatal\", {\n      error: error instanceof Error ? error.message : \"Unknown error\",\n    });\n    process.exit(1);\n  });\n}\n"],"mappings":";;;;;;;;AACA,IAAM,cAAc,SAAS,QAAQ,SAAS,KAAK,MAAM,GAAG,EAAE,CAAC,GAAG,EAAE;AACpE,IAAI,cAAc,IAAI;AACpB,UAAQ,OAAO;AAAA,IACb,+CAA+C,QAAQ,SAAS,IAAI;AAAA;AAAA,EACtE;AACA,UAAQ,KAAK,CAAC;AAChB;AAUA,IAAM,OAAO,QAAQ,KAAK,MAAM,CAAC;AAEjC,SAAS,QAAQ,MAAuB;AACtC,SAAO,KAAK,SAAS,KAAK,IAAI,EAAE;AAClC;AAEA,SAAS,aAAa,MAAkC;AACtD,QAAM,MAAM,KAAK,QAAQ,KAAK,IAAI,EAAE;AACpC,MAAI,OAAO,KAAK,MAAM,IAAI,KAAK,QAAQ;AACrC,WAAO,KAAK,MAAM,CAAC;AAAA,EACrB;AACA,SAAO;AACT;AAEA,IAAI,QAAQ,MAAM,KAAK,QAAQ,GAAG,GAAG;AACnC,UAAQ,OAAO,MAAM;AAAA,IACnB;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EACF,EAAE,KAAK,IAAI,CAAC;AACZ,UAAQ,KAAK,CAAC;AAChB;AAMA,IAAI,QAAQ,MAAM,GAAG;AACnB,QAAM,OAAO,aAAa,MAAM,IAAI,SAAS,aAAa,MAAM,GAAI,EAAE,IAAI;AAC1E,QAAM,WAAW,aAAa,MAAM,KAAK;AAEzC,gBAAc,EAAE,MAAM,SAAS,CAAC,EAAE,MAAM,CAAC,UAAU;AACjD,WAAO,SAAS,kBAAkB;AAAA,MAChC,OAAO,iBAAiB,QAAQ,MAAM,UAAU;AAAA,IAClD,CAAC;AACD,YAAQ,KAAK,CAAC;AAAA,EAChB,CAAC;AACH,OAAO;AACL,iBAAe,EAAE,MAAM,CAAC,UAAU;AAChC,WAAO,SAAS,mBAAmB;AAAA,MACjC,OAAO,iBAAiB,QAAQ,MAAM,UAAU;AAAA,IAClD,CAAC;AACD,YAAQ,KAAK,CAAC;AAAA,EAChB,CAAC;AACH;","names":[]}