specguard-mcp 0.1.0

package/dist/src/tools/repository-overview.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"repository-overview.js","sourceRoot":"","sources":["../../../src/tools/repository-overview.ts"],"names":[],"mappings":"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"}

package/dist/src/tools/types.d.ts

@@ -0,0 +1,111 @@
+import type { Config } from "../config.js";
+import type { RunCommand } from "../support/run-command.js";
+/**
+ * The contract every tool implements — and the whole of what "the toolset grows
+ * gradually" means in code.
+ *
+ * SPGD-310's governing constraint is that *adding a tool later must not
+ * re-architect the server*. That is a statement about coupling, so it is met by
+ * removing the coupling rather than by promising to be careful:
+ * `src/server.ts` reads this interface and the registry array and knows nothing
+ * about any individual tool — no per-tool `switch`, no name it hard-codes, no
+ * branch on which capability is being wrapped. Adding a tool is therefore two
+ * mechanical *wiring* edits:
+ *
+ *   1. a new file under `src/tools/` that default-exports a `ToolDefinition`;
+ *   2. one entry appended to the array in `src/tools/index.ts`.
+ *
+ * There is no third *wiring* edit — but do not read that as "no third edit":
+ * making only the two above turns the suite red, deliberately. Every tool also
+ * earns a `### ` section in `README.md` whose argument table gives every
+ * argument a row, since that README ships as the package's published
+ * documentation and `test/readme.test.ts` derives the obligation from this
+ * registry, so a missing section or an undocumented parameter fails. And
+ * `test/server.test.ts`'s `discovers the bootstrap tools` asserts the advertised
+ * tool names by `deepEqual`, so growing the toolset must update that list — a
+ * pin kept on purpose, so that what this server promises an agent changes only
+ * by a conscious decision (`src/tools/index.ts` says why only these two).
+ * Neither obligation is covered by `test/server.test.ts`'s `adding a tool`
+ * example: that one *injects* a definition through `createServer`'s `tools`
+ * option, which REPLACES the registry rather than growing it, so it proves the
+ * handler path is tool-agnostic and says nothing about what registry growth
+ * costs.
+ *
+ * `test/tools/registry.test.ts` asserts the properties a new entry must satisfy
+ * (unique name, non-empty description, object schema) over whatever the array
+ * holds, so a tool added in six months is checked by tests written today
+ * without anyone remembering to extend them.
+ *
+ * What is deliberately NOT fixed here is the wire shape of any tool's OUTPUT.
+ * The brief leaves the contract open on purpose, and each tool below returns the
+ * shape of the capability it wraps — the linter's own JSON document, the API's
+ * own response body — rather than a house format this server would have to
+ * define, version and translate into. A thin client that reshapes its upstream
+ * is not thin.
+ */
+export interface ToolDefinition {
+    /**
+     * The name the agent calls. Stable once shipped: it is the only part of a
+     * tool an agent's prompt can hard-code.
+     */
+    readonly name: string;
+    /** Short human label for clients that render one. */
+    readonly title: string;
+    /**
+     * What the tool answers, in the terms an agent chooses by.
+     *
+     * This is prompt material, not documentation — it is the entire basis on
+     * which a model decides whether to call the tool, so it says what question
+     * the tool answers and names the limits that would otherwise be discovered
+     * through a failed call.
+     */
+    readonly description: string;
+    /**
+     * A JSON Schema object — passed to the client verbatim.
+     *
+     * Plain JSON Schema rather than a validation library's type: it is what MCP
+     * puts on the wire, so writing it directly removes a translation step and the
+     * class of bug where the advertised schema and the enforced one drift.
+     */
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties?: Record<string, unknown>;
+        readonly required?: readonly string[];
+        readonly additionalProperties?: boolean;
+        readonly [key: string]: unknown;
+    };
+    /**
+     * Runs the tool.
+     *
+     * Throws a `SpecGuardMcpError` for an expected failure — the server renders
+     * it as an MCP tool error the agent can read and act on. Anything else
+     * propagates as a defect.
+     */
+    readonly run: (args: Record<string, unknown>, context: ToolContext) => Promise<ToolResult>;
+}
+/**
+ * Everything a tool is allowed to reach the outside world through.
+ *
+ * Injected rather than imported by the tools themselves, which is what makes
+ * each one testable without a live SpecGuard deployment or an installed Ruby
+ * gem — and what lets a tool added later be tested the same way for free.
+ */
+export interface ToolContext {
+    readonly config: Config;
+    /** Runs a subprocess. No shell is involved; see `run-command.ts`. */
+    readonly runCommand: RunCommand;
+    /** `fetch`, injectable so HTTP-backed tools can be tested against a stub. */
+    readonly fetch: typeof globalThis.fetch;
+}
+/**
+ * What a tool hands back.
+ *
+ * `structured` is the answer as data and is what an agent should read;
+ * `text` is the same answer rendered for a client that shows only text. Both
+ * are derived from one value inside each tool rather than assembled twice, so
+ * they cannot come to disagree about the same call.
+ */
+export interface ToolResult {
+    readonly text: string;
+    readonly structured?: Record<string, unknown>;
+}

package/dist/src/tools/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/src/tools/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/tools/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "specguard-mcp",
+  "version": "0.1.0",
+  "description": "MCP server exposing SpecGuard suite intelligence to AI coding agents",
+  "license": "ISC",
+  "type": "module",
+  "bin": {
+    "specguard-mcp": "dist/bin/specguard-mcp.js"
+  },
+  "main": "dist/src/index.js",
+  "types": "dist/src/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc --project tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "pretest": "tsc --project tsconfig.test.json",
+    "test": "node --test \".test-build/test/**/*.test.js\"",
+    "prepare": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.0",
+    "typescript": "^5.6.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yatfa-ai/specguard-mcp.git"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "specguard",
+    "rspec",
+    "test-intelligence"
+  ]
+}