@agent-lint/mcp 0.3.0 → 0.3.3

package/CHANGELOG.md

@@ -0,0 +1,38 @@
+# @agent-lint/mcp Changelog
+
+## [0.3.3]
+
+### Fixed
+
+- GitLab publish jobs now support both plain and file-based `NPM_TOKEN` variables and fail fast on invalid npm auth
+
+## [0.3.2]
+
+### Changed
+
+- README and npm description now use the current public positioning around structured, current, codebase-aware agent context
+- Public repository cleanup removed internal planning docs from the published surface
+
+## [0.3.1]
+
+### Changed
+
+- README, npm metadata, and release metadata now match the current 4-tool MCP surface
+
+### Fixed
+
+- Tool timeout wiring is now attached to the active public tools
+- Server version resolution now prefers the package version instead of unrelated workspace env values
+
+## [0.3.0]
+
+### Added
+
+- Read-only MCP server with 4 tools and 3 resources
+- Stdio and HTTP transports
+- Programmatic server creation helpers
+
+### Fixed
+
+- Current tool timeout wiring now matches the public tool surface
+- Server version reporting now resolves to the real package version

package/README.md

@@ -1,121 +1,39 @@
 # @agent-lint/mcp
 
-MCP server for AI agent context artifact orchestration.
+Read-only MCP server for keeping `AGENTS.md`, rules, and skills structured, current, and codebase-aware.
 
-**Zero LLM dependencies.** Fully deterministic. Local-first. No database. No auth.
-
-## What It Does
-
-Provides a [Model Context Protocol](https://modelcontextprotocol.io/) server that guides your coding agent in creating, maintaining, and improving AI-agent context artifacts:
-
-- `AGENTS.md` / `CLAUDE.md`
-- Skills, Rules, Workflows, Plans
-
-Comprehensive guidelines, workspace scanning, maintenance rules, and repeatable improvement loops — all without calling any LLM.
-
-## Quick Start
+## Start the Server
 
 ```bash
 npx -y @agent-lint/mcp
 ```
 
-## MCP Client Configuration
-
-### Cursor
-
-Add to `.cursor/mcp.json`:
-
-```json
-{
-  "mcpServers": {
-    "agentlint": {
-      "command": "npx",
-      "args": ["-y", "@agent-lint/mcp"]
-    }
-  }
-}
-```
-
-### Claude Desktop
-
-Add to `claude_desktop_config.json`:
-
-```json
-{
-  "mcpServers": {
-    "agentlint": {
-      "command": "npx",
-      "args": ["-y", "@agent-lint/mcp"]
-    }
-  }
-}
-```
-
-### VS Code
-
-Add to `.vscode/mcp.json`:
-
-```json
-{
-  "servers": {
-    "agentlint": {
-      "type": "stdio",
-      "command": "npx",
-      "args": ["-y", "@agent-lint/mcp"]
-    }
-  }
-}
-```
+For most users, the fastest setup path is still:
 
-### Windsurf
-
-Add to `.windsurf/mcp_config.json`:
-
-```json
-{
-  "mcpServers": {
-    "agentlint": {
-      "command": "npx",
-      "args": ["-y", "@agent-lint/mcp"]
-    }
-  }
-}
+```bash
+npx @agent-lint/cli init
 ```
 
-## Available Tools (4)
+## Current Tool Surface
 
-| Tool | Description |
-| ---- | ----------- |
-| `agentlint_get_guidelines` | Returns comprehensive guidelines for creating or updating any artifact type — mandatory sections, do/don't lists, anti-patterns, templates, and quality checklist |
-| `agentlint_plan_workspace_autofix` | Scans your workspace, discovers all context artifacts, identifies missing files and incomplete sections, and returns a step-by-step fix plan |
-| `agentlint_quick_check` | After structural changes (new modules, config changes, dependency updates), checks if context artifacts need updating |
-| `agentlint_emit_maintenance_snippet` | Returns a persistent rule snippet for your IDE that keeps your agent maintaining context automatically |
+| Tool | Purpose |
+| --- | --- |
+| `agentlint_get_guidelines` | Return artifact guidance before creating or updating context files |
+| `agentlint_plan_workspace_autofix` | Scan a workspace and return a step-by-step fix plan |
+| `agentlint_quick_check` | Decide whether recent code changes require context updates |
+| `agentlint_emit_maintenance_snippet` | Return a reusable maintenance rule snippet for supported IDEs |
 
-## MCP Resources (3)
+## Current Resource Surface
 
-| Resource | Content |
-| -------- | ------- |
-| `agentlint://guidelines/{type}` | Full guidelines for an artifact type |
-| `agentlint://template/{type}` | Skeleton template for creating a new artifact |
-| `agentlint://path-hints/{type}` | File discovery patterns per IDE client |
-
-## Supported Artifact Types
-
-| Type | File Patterns |
-| ---- | ------------- |
-| **Agents** | `AGENTS.md`, `CLAUDE.md`, `.github/copilot-instructions.md` |
-| **Rules** | `.cursor/rules/*.md`, `.windsurf/rules/*.md` |
-| **Skills** | `.cursor/skills/*/SKILL.md`, `.windsurf/skills/*/SKILL.md` |
-| **Workflows** | `.cursor/workflows/*.md`, `.windsurf/workflows/*.md` |
-| **Plans** | `docs/*.md`, `.windsurf/plans/*.md` |
-
-## Quality Metrics (12)
-
-`clarity` · `specificity` · `scope-control` · `completeness` · `actionability` · `verifiability` · `safety` · `injection-resistance` · `secret-hygiene` · `token-efficiency` · `platform-fit` · `maintainability`
+| Resource | Purpose |
+| --- | --- |
+| `agentlint://guidelines/{type}` | Readable guidelines for one artifact type |
+| `agentlint://template/{type}` | Skeleton template for a new artifact |
+| `agentlint://path-hints/{type}` | IDE-specific file discovery hints |
 
 ## Programmatic Usage
 
-```typescript
+```ts
 import { createAgentLintMcpServer } from "@agent-lint/mcp";
 
 const server = createAgentLintMcpServer({
@@ -129,17 +47,23 @@ const server = createAgentLintMcpServer({
 npx @agent-lint/mcp --http --port 3001
 ```
 
-## Design Principles
+Notes:
+
+- HTTP mode keeps the public surface read-only.
+- Workspace scanning is disabled in HTTP mode unless you explicitly enable it.
+
+## Design Constraints
 
-- **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. Agent Lint provides guidance — your coding agent does the work.
-- **Minimum Dependencies**: Published package under 500 KB packed.
+- No server-side LLM calls
+- No database or cache
+- No file writes from the MCP server
+- Local stderr logging only
 
 ## Related
 
-- [`@agent-lint/cli`](https://www.npmjs.com/package/@agent-lint/cli) — CLI interface
-- [Repository](https://gitlab.com/bsamilozturk/agentlint)
+- [Root README](https://github.com/samilytu/agentlint)
+- [CLI package](https://www.npmjs.com/package/@agent-lint/cli)
+- [Authoritative publish source](https://gitlab.com/bsamilozturk/agentlint)
 
 ## License
 

package/dist/bin.js

@@ -4,7 +4,7 @@ import {
   logMcp,
   runHttpServer,
   runStdioServer
-} from "./chunk-ZYDIOQXE.js";
+} from "./chunk-DYP46E6V.js";
 
 // src/bin.ts
 var nodeVersion = parseInt(process.versions.node.split(".")[0], 10);

package/dist/catalog.d.ts

@@ -0,0 +1,5 @@
+export declare const CURRENT_TOOL_IDS: readonly ["agentlint_get_guidelines", "agentlint_plan_workspace_autofix", "agentlint_quick_check", "agentlint_emit_maintenance_snippet"];
+export declare const CURRENT_RESOURCE_URIS: readonly ["agentlint://guidelines/{type}", "agentlint://template/{type}", "agentlint://path-hints/{type}"];
+export declare const CURRENT_TOOL_TIMEOUTS: Record<(typeof CURRENT_TOOL_IDS)[number], number>;
+export declare const LEGACY_TOOL_TIMEOUT_ALIASES: Record<string, number>;
+//# sourceMappingURL=catalog.d.ts.map

package/dist/catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../src/catalog.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,gBAAgB,0IAKnB,CAAC;AAEX,eAAO,MAAM,qBAAqB,4GAIxB,CAAC;AAEX,eAAO,MAAM,qBAAqB,EAAE,MAAM,CAAC,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,EAAE,MAAM,CAKnF,CAAC;AAEF,eAAO,MAAM,2BAA2B,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAU9D,CAAC"}

package/dist/{chunk-ZYDIOQXE.js → chunk-DYP46E6V.js}

@@ -18915,6 +18915,115 @@ function registerAgentLintResources(server) {
   );
 }
 
+// src/logger.ts
+function logMcp(level, event, fields = {}) {
+  const payload = {
+    ts: (/* @__PURE__ */ new Date()).toISOString(),
+    level,
+    event,
+    ...fields
+  };
+  console.error(JSON.stringify(payload));
+}
+
+// src/catalog.ts
+var CURRENT_TOOL_TIMEOUTS = {
+  agentlint_get_guidelines: 3e4,
+  agentlint_plan_workspace_autofix: 6e4,
+  agentlint_quick_check: 3e4,
+  agentlint_emit_maintenance_snippet: 1e4
+};
+var LEGACY_TOOL_TIMEOUT_ALIASES = {
+  analyze_artifact: 3e4,
+  analyze_workspace_artifacts: 6e4,
+  analyze_context_bundle: 3e4,
+  prepare_artifact_fix_context: 3e4,
+  submit_client_assessment: 3e4,
+  suggest_patch: 3e4,
+  quality_gate_artifact: 3e4,
+  apply_patches: 15e3,
+  validate_export: 1e4
+};
+
+// src/transport-security.ts
+var MAX_JSONRPC_MESSAGE_BYTES = 10 * 1024 * 1024;
+var TOOL_TIMEOUTS = {
+  ...CURRENT_TOOL_TIMEOUTS,
+  ...LEGACY_TOOL_TIMEOUT_ALIASES
+};
+var DEFAULT_TOOL_TIMEOUT_MS = 3e4;
+function applyMessageSizeGuard(transport, maxBytes = MAX_JSONRPC_MESSAGE_BYTES) {
+  const originalStart = transport.start.bind(transport);
+  transport.start = async function() {
+    await originalStart();
+    const downstream = transport.onmessage;
+    if (!downstream) {
+      return;
+    }
+    transport.onmessage = (message, extra) => {
+      const serialized = JSON.stringify(message);
+      const byteLength = Buffer.byteLength(serialized, "utf8");
+      if (byteLength > maxBytes) {
+        logMcp("warn", "transport.message_too_large", {
+          byteLength,
+          maxBytes,
+          preview: serialized.slice(0, 200)
+        });
+        if (transport.onerror) {
+          transport.onerror(
+            new Error(`JSON-RPC message too large: ${byteLength} bytes (limit: ${maxBytes} bytes)`)
+          );
+        }
+        return;
+      }
+      downstream(message, extra);
+    };
+  };
+  return transport;
+}
+var ToolTimeoutError = class extends Error {
+  toolName;
+  timeoutMs;
+  constructor(toolName, timeoutMs) {
+    super(`Tool "${toolName}" timed out after ${timeoutMs}ms`);
+    this.name = "ToolTimeoutError";
+    this.toolName = toolName;
+    this.timeoutMs = timeoutMs;
+  }
+};
+function getToolTimeout(toolName) {
+  return TOOL_TIMEOUTS[toolName] ?? DEFAULT_TOOL_TIMEOUT_MS;
+}
+async function withToolTimeout(toolName, fn, timeoutMs) {
+  const ms = timeoutMs ?? getToolTimeout(toolName);
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const timer = setTimeout(() => {
+      if (!settled) {
+        settled = true;
+        logMcp("warn", "tool.timeout", { toolName, timeoutMs: ms });
+        reject(new ToolTimeoutError(toolName, ms));
+      }
+    }, ms);
+    fn().then(
+      (result) => {
+        if (!settled) {
+          settled = true;
+          clearTimeout(timer);
+          resolve(result);
+        }
+      },
+      (error48) => {
+        if (!settled) {
+          settled = true;
+          clearTimeout(timer);
+          reject(error48);
+        }
+      }
+    );
+  });
+}
+
 // src/tools/schema-compat.ts
 function asInputSchema(schema) {
   return schema;
@@ -18948,8 +19057,9 @@ function toErrorResult(message) {
 
 // src/tools/get-guidelines.ts
 function registerGetGuidelinesTool(server) {
+  const toolName = "agentlint_get_guidelines";
   server.registerTool(
-    "agentlint_get_guidelines",
+    toolName,
     {
       title: "Get Guidelines",
       description: "Returns comprehensive Markdown guidelines for creating or updating a context artifact (AGENTS.md, skills, rules, workflows, plans). Includes mandatory sections, do/don't lists, anti-patterns, quality checklist, template skeleton, and client-specific hints. Call this tool before creating or editing any AI agent context artifact file.",
@@ -18962,11 +19072,11 @@ function registerGetGuidelinesTool(server) {
     },
     asToolHandler(async (args) => {
       try {
-        const markdown = buildGuidelines(args.type, args.client ?? "generic");
+        const markdown = await withToolTimeout(toolName, async () => buildGuidelines(args.type, args.client ?? "generic"));
         return toMarkdownResult(markdown);
       } catch (error48) {
         const message = error48 instanceof Error ? error48.message : "Unknown error";
-        return toErrorResult(`agentlint_get_guidelines failed: ${message}`);
+        return toErrorResult(`${toolName} failed: ${message}`);
       }
     })
   );
@@ -18974,11 +19084,12 @@ function registerGetGuidelinesTool(server) {
 
 // src/tools/plan-workspace-autofix.ts
 function registerPlanWorkspaceAutofixTool(server, options2) {
+  const toolName = "agentlint_plan_workspace_autofix";
   if (!options2.enabled) {
     return;
   }
   server.registerTool(
-    "agentlint_plan_workspace_autofix",
+    toolName,
     {
       title: "Plan Workspace Autofix",
       description: "Scans the workspace for all AI agent context artifact files (AGENTS.md, CLAUDE.md, skills, rules, workflows, plans), identifies missing files and incomplete sections, and returns a step-by-step Markdown action plan. The LLM should execute the plan using its file reading and editing capabilities. Call this when the user asks to review, fix, or improve all context artifacts in a project.",
@@ -18992,11 +19103,11 @@ function registerPlanWorkspaceAutofixTool(server, options2) {
     asToolHandler(async (args) => {
       try {
         const rootPath = args.rootPath ?? process.cwd();
-        const plan = buildWorkspaceAutofixPlan(rootPath);
+        const plan = await withToolTimeout(toolName, async () => buildWorkspaceAutofixPlan(rootPath));
         return toMarkdownResult(plan.markdown);
       } catch (error48) {
         const message = error48 instanceof Error ? error48.message : "Unknown error";
-        return toErrorResult(`agentlint_plan_workspace_autofix failed: ${message}`);
+        return toErrorResult(`${toolName} failed: ${message}`);
       }
     })
   );
@@ -19004,8 +19115,9 @@ function registerPlanWorkspaceAutofixTool(server, options2) {
 
 // src/tools/quick-check.ts
 function registerQuickCheckTool(server) {
+  const toolName = "agentlint_quick_check";
   server.registerTool(
-    "agentlint_quick_check",
+    toolName,
     {
       title: "Quick Check",
       description: "Checks whether recent code changes require updates to AI agent context artifacts. Provide changed file paths and/or a description of what changed. Returns signals indicating which artifacts (AGENTS.md, rules, workflows, etc.) may need updating and what action to take. Call this after structural changes like adding modules, changing configs, or modifying dependencies.",
@@ -19018,11 +19130,11 @@ function registerQuickCheckTool(server) {
     },
     asToolHandler(async (args) => {
       try {
-        const result = runQuickCheck(args.changedPaths, args.changeDescription);
+        const result = await withToolTimeout(toolName, async () => runQuickCheck(args.changedPaths, args.changeDescription));
         return toMarkdownResult(result.markdown);
       } catch (error48) {
         const message = error48 instanceof Error ? error48.message : "Unknown error";
-        return toErrorResult(`agentlint_quick_check failed: ${message}`);
+        return toErrorResult(`${toolName} failed: ${message}`);
       }
     })
   );
@@ -19030,8 +19142,9 @@ function registerQuickCheckTool(server) {
 
 // src/tools/emit-maintenance-snippet.ts
 function registerEmitMaintenanceSnippetTool(server) {
+  const toolName = "agentlint_emit_maintenance_snippet";
   server.registerTool(
-    "agentlint_emit_maintenance_snippet",
+    toolName,
     {
       title: "Emit Maintenance Snippet",
       description: "Returns a persistent rule snippet that you should add to the user's IDE rules file. Once added, these rules ensure the LLM agent automatically maintains context artifacts (AGENTS.md, skills, rules, workflows, plans) whenever structural changes happen. Supports Cursor, Windsurf, VS Code, Claude Code, and generic formats. Call this when the user asks to set up automatic context maintenance.",
@@ -19044,11 +19157,11 @@ function registerEmitMaintenanceSnippetTool(server) {
     },
     asToolHandler(async (args) => {
       try {
-        const result = buildMaintenanceSnippet(args.client ?? "generic");
+        const result = await withToolTimeout(toolName, async () => buildMaintenanceSnippet(args.client ?? "generic"));
         return toMarkdownResult(result.markdown);
       } catch (error48) {
         const message = error48 instanceof Error ? error48.message : "Unknown error";
-        return toErrorResult(`agentlint_emit_maintenance_snippet failed: ${message}`);
+        return toErrorResult(`${toolName} failed: ${message}`);
       }
     })
   );
@@ -19063,6 +19176,7 @@ function registerAgentLintTools(server, options2) {
 }
 
 // src/server.ts
+import { readFileSync } from "fs";
 import { McpServer as McpServer2 } from "@modelcontextprotocol/sdk/server/mcp.js";
 var DEFAULT_MCP_SERVER_NAME = "agentlint";
 var DEFAULT_MCP_INSTRUCTIONS = [
@@ -19075,7 +19189,22 @@ var DEFAULT_MCP_INSTRUCTIONS = [
   "Apply recommended changes directly using your file editing capabilities."
 ].join(" ");
 function resolveServerVersion() {
-  return process.env.npm_package_version ?? "0.2.0";
+  if (process.env.npm_package_name === "@agent-lint/mcp" && process.env.npm_package_version) {
+    return process.env.npm_package_version;
+  }
+  if ("0.3.3".length > 0) {
+    return "0.3.3";
+  }
+  try {
+    const pkg = JSON.parse(
+      readFileSync(new URL("../package.json", import.meta.url), "utf-8")
+    );
+    if (typeof pkg.version === "string" && pkg.version.length > 0) {
+      return pkg.version;
+    }
+  } catch {
+  }
+  return "0.0.0-dev";
 }
 function resolveWorkspaceScanEnabled(options2) {
   if (typeof options2.enableWorkspaceScan === "boolean") {
@@ -19087,7 +19216,7 @@ function resolveWorkspaceScanEnabled(options2) {
   if (options2.transportMode === "http") {
     return process.env.MCP_ENABLE_WORKSPACE_SCAN === "true";
   }
-  return process.env.MCP_ENABLE_WORKSPACE_SCAN === "true";
+  return process.env.MCP_ENABLE_WORKSPACE_SCAN !== "false";
 }
 function resolveInstructions(options2, workspaceScanEnabled) {
   if (options2.instructions) {
@@ -19125,103 +19254,6 @@ function createAgentLintMcpServer(options2 = {}) {
   return server;
 }
 
-// src/logger.ts
-function logMcp(level, event, fields = {}) {
-  const payload = {
-    ts: (/* @__PURE__ */ new Date()).toISOString(),
-    level,
-    event,
-    ...fields
-  };
-  console.error(JSON.stringify(payload));
-}
-
-// src/transport-security.ts
-var MAX_JSONRPC_MESSAGE_BYTES = 10 * 1024 * 1024;
-var TOOL_TIMEOUTS = {
-  analyze_artifact: 3e4,
-  analyze_workspace_artifacts: 6e4,
-  analyze_context_bundle: 3e4,
-  prepare_artifact_fix_context: 3e4,
-  submit_client_assessment: 3e4,
-  suggest_patch: 3e4,
-  quality_gate_artifact: 3e4,
-  apply_patches: 15e3,
-  validate_export: 1e4
-};
-var DEFAULT_TOOL_TIMEOUT_MS = 3e4;
-function applyMessageSizeGuard(transport, maxBytes = MAX_JSONRPC_MESSAGE_BYTES) {
-  const originalStart = transport.start.bind(transport);
-  transport.start = async function() {
-    await originalStart();
-    const downstream = transport.onmessage;
-    if (!downstream) {
-      return;
-    }
-    transport.onmessage = (message, extra) => {
-      const serialized = JSON.stringify(message);
-      const byteLength = Buffer.byteLength(serialized, "utf8");
-      if (byteLength > maxBytes) {
-        logMcp("warn", "transport.message_too_large", {
-          byteLength,
-          maxBytes,
-          preview: serialized.slice(0, 200)
-        });
-        if (transport.onerror) {
-          transport.onerror(
-            new Error(`JSON-RPC message too large: ${byteLength} bytes (limit: ${maxBytes} bytes)`)
-          );
-        }
-        return;
-      }
-      downstream(message, extra);
-    };
-  };
-  return transport;
-}
-var ToolTimeoutError = class extends Error {
-  toolName;
-  timeoutMs;
-  constructor(toolName, timeoutMs) {
-    super(`Tool "${toolName}" timed out after ${timeoutMs}ms`);
-    this.name = "ToolTimeoutError";
-    this.toolName = toolName;
-    this.timeoutMs = timeoutMs;
-  }
-};
-function getToolTimeout(toolName) {
-  return TOOL_TIMEOUTS[toolName] ?? DEFAULT_TOOL_TIMEOUT_MS;
-}
-async function withToolTimeout(toolName, fn, timeoutMs) {
-  const ms = timeoutMs ?? getToolTimeout(toolName);
-  return new Promise((resolve, reject) => {
-    let settled = false;
-    const timer = setTimeout(() => {
-      if (!settled) {
-        settled = true;
-        logMcp("warn", "tool.timeout", { toolName, timeoutMs: ms });
-        reject(new ToolTimeoutError(toolName, ms));
-      }
-    }, ms);
-    fn().then(
-      (result) => {
-        if (!settled) {
-          settled = true;
-          clearTimeout(timer);
-          resolve(result);
-        }
-      },
-      (error48) => {
-        if (!settled) {
-          settled = true;
-          clearTimeout(timer);
-          reject(error48);
-        }
-      }
-    );
-  });
-}
-
 // src/stdio.ts
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 async function runStdioServer() {
@@ -19601,9 +19633,6 @@ async function runHttpServer(options2 = {}) {
 export {
   registerAgentLintPrompts,
   registerAgentLintResources,
-  registerAgentLintTools,
-  DEFAULT_MCP_SERVER_NAME,
-  createAgentLintMcpServer,
   logMcp,
   MAX_JSONRPC_MESSAGE_BYTES,
   TOOL_TIMEOUTS,
@@ -19612,6 +19641,9 @@ export {
   ToolTimeoutError,
   getToolTimeout,
   withToolTimeout,
+  registerAgentLintTools,
+  DEFAULT_MCP_SERVER_NAME,
+  createAgentLintMcpServer,
   runStdioServer,
   startRateLimitCleanup,
   stopRateLimitCleanup,
@@ -19641,4 +19673,4 @@ strip-bom-string/index.js:
    * Released under the MIT License.
    *)
 */
-//# sourceMappingURL=chunk-ZYDIOQXE.js.map
+//# sourceMappingURL=chunk-DYP46E6V.js.map