@shrkcrft/mcp-server 0.1.0-alpha.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SharkCraft 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,15 @@
+# @shrkcrft/mcp-server
+
+SharkCraft MCP server: 25 tools over @modelcontextprotocol/sdk's stdio transport.
+
+Part of [SharkCraft](https://github.com/sharkcraft/sharkcraft) — a deterministic, local-first toolkit that gives AI coding agents durable project context. See the main repo for documentation, examples, and the `shrk` CLI.
+
+## Install
+
+```bash
+bun add @shrkcrft/mcp-server
+```
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { startMcpServer, createSharkcraftServer, resolveTargetRoot, type StartMcpServerOptions, type CreateSharkcraftServerOptions, } from './server/create-mcp-server.js';
+export { startHttpServer, type HttpServerHandle } from './server/http-transport.js';
+export { startSharkcraftWatcher } from './server/sharkcraft-watcher.js';
+export { ALL_TOOLS } from './tools/index.js';
+export type { IToolDefinition, IToolResponse, IToolContext, IMcpGateDecision, McpGateResolver, } from './server/tool-definition.js';
+export { MCP_PROTOCOL_VERSION, MCP_SERVER_NAME, MCP_SERVER_VERSION, } from './server/mcp-server-config.js';
+export { buildResourceList, readResource, parseResourceUri, knowledgeUri, templateUri, docUri, OVERVIEW_URI, AGENT_INSTRUCTIONS_URI, URI_SCHEME, } from './resources/index.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,EACd,sBAAsB,EACtB,iBAAiB,EACjB,KAAK,qBAAqB,EAC1B,KAAK,6BAA6B,GACnC,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAE,eAAe,EAAE,KAAK,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AACpF,OAAO,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAC;AACxE,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAK7C,YAAY,EACV,eAAe,EACf,aAAa,EACb,YAAY,EACZ,gBAAgB,EAChB,eAAe,GAChB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EACL,oBAAoB,EACpB,eAAe,EACf,kBAAkB,GACnB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EACL,iBAAiB,EACjB,YAAY,EACZ,gBAAgB,EAChB,YAAY,EACZ,WAAW,EACX,MAAM,EACN,YAAY,EACZ,sBAAsB,EACtB,UAAU,GACX,MAAM,sBAAsB,CAAC"}

package/dist/index.js

@@ -0,0 +1,6 @@
+export { startMcpServer, createSharkcraftServer, resolveTargetRoot, } from "./server/create-mcp-server.js";
+export { startHttpServer } from "./server/http-transport.js";
+export { startSharkcraftWatcher } from "./server/sharkcraft-watcher.js";
+export { ALL_TOOLS } from "./tools/index.js";
+export { MCP_PROTOCOL_VERSION, MCP_SERVER_NAME, MCP_SERVER_VERSION, } from "./server/mcp-server-config.js";
+export { buildResourceList, readResource, parseResourceUri, knowledgeUri, templateUri, docUri, OVERVIEW_URI, AGENT_INSTRUCTIONS_URI, URI_SCHEME, } from "./resources/index.js";

package/dist/main.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env bun
+export {};
+//# sourceMappingURL=main.d.ts.map

package/dist/main.d.ts.map

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

package/dist/main.js

@@ -0,0 +1,43 @@
+#!/usr/bin/env bun
+import { startMcpServer } from "./server/create-mcp-server.js";
+function extractFlag(argv, name) {
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === `--${name}`) {
+            const next = argv[i + 1];
+            if (next !== undefined && !next.startsWith('-'))
+                return next;
+            return undefined;
+        }
+        if (arg.startsWith(`--${name}=`))
+            return arg.slice(name.length + 3);
+    }
+    return undefined;
+}
+function hasFlag(argv, name) {
+    return argv.includes(`--${name}`);
+}
+const argv = process.argv.slice(2);
+const verbose = hasFlag(argv, 'verbose') || process.env.SHARKCRAFT_MCP_VERBOSE === '1';
+const watch = hasFlag(argv, 'watch');
+const cliCwd = extractFlag(argv, 'cwd');
+const useHttp = hasFlag(argv, 'http');
+const host = extractFlag(argv, 'host');
+const portStr = extractFlag(argv, 'port');
+const port = portStr ? Number(portStr) : undefined;
+const opts = {
+    cwd: cliCwd,
+    verbose,
+    watch,
+};
+if (useHttp) {
+    opts.transport = 'http';
+    if (host)
+        opts.host = host;
+    if (port !== undefined && Number.isFinite(port))
+        opts.port = port;
+}
+startMcpServer(opts).catch((e) => {
+    process.stderr.write(`[mcp] fatal: ${e instanceof Error ? e.message : String(e)}\n`);
+    process.exit(1);
+});

package/dist/resources/build-resource-list.d.ts

@@ -0,0 +1,14 @@
+import type { ISharkcraftInspection } from '@shrkcrft/inspector';
+export interface IResourceListItem {
+    uri: string;
+    name: string;
+    description?: string;
+    mimeType?: string;
+}
+/**
+ * Resources advertised by SharkCraft. Read-only by design — there is no
+ * resource-write endpoint. AI agents use these to fetch background info
+ * without invoking a tool call.
+ */
+export declare function buildResourceList(inspection: ISharkcraftInspection): IResourceListItem[];
+//# sourceMappingURL=build-resource-list.d.ts.map

package/dist/resources/build-resource-list.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-resource-list.d.ts","sourceRoot":"","sources":["../../src/resources/build-resource-list.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AASjE,MAAM,WAAW,iBAAiB;IAChC,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,qBAAqB,GAAG,iBAAiB,EAAE,CAqDxF"}

package/dist/resources/build-resource-list.js

@@ -0,0 +1,56 @@
+import { extname, basename } from 'node:path';
+import { AGENT_INSTRUCTIONS_URI, docUri, knowledgeUri, OVERVIEW_URI, templateUri, } from "./resource-uris.js";
+/**
+ * Resources advertised by SharkCraft. Read-only by design — there is no
+ * resource-write endpoint. AI agents use these to fetch background info
+ * without invoking a tool call.
+ */
+export function buildResourceList(inspection) {
+    const items = [];
+    items.push({
+        uri: OVERVIEW_URI,
+        name: 'Project overview',
+        description: 'Compact project summary (name, package manager, frameworks, scripts).',
+        mimeType: 'text/plain',
+    });
+    items.push({
+        uri: AGENT_INSTRUCTIONS_URI,
+        name: 'Agent instructions',
+        description: 'How AI agents should use SharkCraft tools and resources.',
+        mimeType: 'text/markdown',
+    });
+    for (const entry of inspection.knowledgeEntries) {
+        items.push({
+            uri: knowledgeUri(entry.id),
+            name: entry.title,
+            description: `[${entry.type}, ${entry.priority}] ${entry.summary ?? ''}`.trim(),
+            mimeType: 'text/markdown',
+        });
+    }
+    for (const template of inspection.templates) {
+        items.push({
+            uri: templateUri(template.id),
+            name: `Template: ${template.name}`,
+            description: template.description,
+            mimeType: 'application/json',
+        });
+    }
+    // Markdown source docs — discoverable via inspection.sourceFiles, but we
+    // expose only .md files. The `path` field becomes the URI path component.
+    for (const sourceFile of inspection.sourceFiles) {
+        if (extname(sourceFile).toLowerCase() !== '.md')
+            continue;
+        const sharkcraftDir = inspection.sharkcraftDir;
+        let relPath = basename(sourceFile);
+        if (sharkcraftDir && sourceFile.startsWith(sharkcraftDir + '/')) {
+            relPath = sourceFile.slice(sharkcraftDir.length + 1);
+        }
+        items.push({
+            uri: docUri(relPath),
+            name: `Doc: ${relPath}`,
+            description: `Source markdown file at sharkcraft/${relPath}`,
+            mimeType: 'text/markdown',
+        });
+    }
+    return items;
+}

package/dist/resources/index.d.ts

@@ -0,0 +1,4 @@
+export * from './resource-uris.js';
+export * from './build-resource-list.js';
+export * from './read-resource.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/resources/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/resources/index.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAC;AACnC,cAAc,0BAA0B,CAAC;AACzC,cAAc,oBAAoB,CAAC"}

package/dist/resources/index.js

@@ -0,0 +1,3 @@
+export * from "./resource-uris.js";
+export * from "./build-resource-list.js";
+export * from "./read-resource.js";

package/dist/resources/read-resource.d.ts

@@ -0,0 +1,16 @@
+import type { ISharkcraftInspection } from '@shrkcrft/inspector';
+export interface IResourceContent {
+    uri: string;
+    mimeType: string;
+    text: string;
+}
+export interface IReadResourceResult {
+    ok: true;
+    contents: IResourceContent[];
+}
+export interface IReadResourceError {
+    ok: false;
+    error: string;
+}
+export declare function readResource(inspection: ISharkcraftInspection, uri: string): IReadResourceResult | IReadResourceError;
+//# sourceMappingURL=read-resource.d.ts.map

package/dist/resources/read-resource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"read-resource.d.ts","sourceRoot":"","sources":["../../src/resources/read-resource.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAKjE,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,IAAI,CAAC;IACT,QAAQ,EAAE,gBAAgB,EAAE,CAAC;CAC9B;AAED,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,KAAK,CAAC;IACV,KAAK,EAAE,MAAM,CAAC;CACf;AAED,wBAAgB,YAAY,CAC1B,UAAU,EAAE,qBAAqB,EACjC,GAAG,EAAE,MAAM,GACV,mBAAmB,GAAG,kBAAkB,CAiG1C"}

package/dist/resources/read-resource.js

@@ -0,0 +1,97 @@
+import { existsSync, readFileSync } from 'node:fs';
+import * as nodePath from 'node:path';
+import { buildProjectOverview, renderOverviewText, AGENT_INSTRUCTIONS } from '@shrkcrft/inspector';
+import { formatEntryFull } from '@shrkcrft/knowledge';
+import { parseResourceUri } from "./resource-uris.js";
+export function readResource(inspection, uri) {
+    const parsed = parseResourceUri(uri);
+    if (parsed.kind === 'overview') {
+        const overview = buildProjectOverview(inspection.workspace, inspection.config?.projectName);
+        return {
+            ok: true,
+            contents: [
+                {
+                    uri,
+                    mimeType: 'text/plain',
+                    text: renderOverviewText(overview),
+                },
+            ],
+        };
+    }
+    if (parsed.kind === 'agent-instructions') {
+        return {
+            ok: true,
+            contents: [{ uri, mimeType: 'text/markdown', text: AGENT_INSTRUCTIONS }],
+        };
+    }
+    if (parsed.kind === 'knowledge' && parsed.id) {
+        const entry = inspection.index.get(parsed.id);
+        if (!entry)
+            return { ok: false, error: `No knowledge entry with id "${parsed.id}".` };
+        return {
+            ok: true,
+            contents: [
+                {
+                    uri,
+                    mimeType: 'text/markdown',
+                    text: formatEntryFull(entry),
+                },
+            ],
+        };
+    }
+    if (parsed.kind === 'template' && parsed.id) {
+        const template = inspection.templateRegistry.get(parsed.id);
+        if (!template)
+            return { ok: false, error: `No template with id "${parsed.id}".` };
+        const safe = {
+            id: template.id,
+            name: template.name,
+            description: template.description,
+            tags: template.tags,
+            scope: template.scope,
+            appliesWhen: template.appliesWhen,
+            variables: template.variables,
+            postGenerationNotes: template.postGenerationNotes ?? [],
+            related: template.related ?? [],
+        };
+        return {
+            ok: true,
+            contents: [
+                {
+                    uri,
+                    mimeType: 'application/json',
+                    text: JSON.stringify(safe, null, 2),
+                },
+            ],
+        };
+    }
+    if (parsed.kind === 'docs' && parsed.path) {
+        if (!inspection.sharkcraftDir) {
+            return { ok: false, error: 'No sharkcraft/ folder is available.' };
+        }
+        // Resolve and verify the doc path lives inside sharkcraftDir.
+        const candidate = nodePath.resolve(inspection.sharkcraftDir, parsed.path);
+        const relative = nodePath.relative(inspection.sharkcraftDir, candidate);
+        if (relative === '' || relative.startsWith('..') || nodePath.isAbsolute(relative)) {
+            return { ok: false, error: `Doc path escapes sharkcraft/: ${parsed.path}` };
+        }
+        if (!existsSync(candidate)) {
+            return { ok: false, error: `Doc file not found: ${parsed.path}` };
+        }
+        let text;
+        try {
+            text = readFileSync(candidate, 'utf8');
+        }
+        catch (e) {
+            return {
+                ok: false,
+                error: `Failed to read doc ${parsed.path}: ${e.message}`,
+            };
+        }
+        return {
+            ok: true,
+            contents: [{ uri, mimeType: 'text/markdown', text }],
+        };
+    }
+    return { ok: false, error: `Unsupported resource URI: ${uri}` };
+}

package/dist/resources/resource-uris.d.ts

@@ -0,0 +1,14 @@
+export declare const URI_SCHEME = "sharkcraft";
+export declare const OVERVIEW_URI = "sharkcraft://overview";
+export declare const AGENT_INSTRUCTIONS_URI = "sharkcraft://agent-instructions";
+export declare function knowledgeUri(id: string): string;
+export declare function templateUri(id: string): string;
+export declare function docUri(relativePath: string): string;
+export interface ParsedResourceUri {
+    scheme: string;
+    kind: 'overview' | 'agent-instructions' | 'knowledge' | 'template' | 'docs' | 'unknown';
+    id?: string;
+    path?: string;
+}
+export declare function parseResourceUri(uri: string): ParsedResourceUri;
+//# sourceMappingURL=resource-uris.d.ts.map

package/dist/resources/resource-uris.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource-uris.d.ts","sourceRoot":"","sources":["../../src/resources/resource-uris.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,UAAU,eAAe,CAAC;AAEvC,eAAO,MAAM,YAAY,0BAA6B,CAAC;AACvD,eAAO,MAAM,sBAAsB,oCAAuC,CAAC;AAE3E,wBAAgB,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAE/C;AAED,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAE9C;AAED,wBAAgB,MAAM,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,UAAU,GAAG,oBAAoB,GAAG,WAAW,GAAG,UAAU,GAAG,MAAM,GAAG,SAAS,CAAC;IACxF,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,iBAAiB,CAwB/D"}

package/dist/resources/resource-uris.js

@@ -0,0 +1,38 @@
+export const URI_SCHEME = 'sharkcraft';
+export const OVERVIEW_URI = `${URI_SCHEME}://overview`;
+export const AGENT_INSTRUCTIONS_URI = `${URI_SCHEME}://agent-instructions`;
+export function knowledgeUri(id) {
+    return `${URI_SCHEME}://knowledge/${encodeURIComponent(id)}`;
+}
+export function templateUri(id) {
+    return `${URI_SCHEME}://template/${encodeURIComponent(id)}`;
+}
+export function docUri(relativePath) {
+    return `${URI_SCHEME}://docs/${relativePath.split('/').map(encodeURIComponent).join('/')}`;
+}
+export function parseResourceUri(uri) {
+    if (!uri.startsWith(`${URI_SCHEME}://`)) {
+        return { scheme: 'unknown', kind: 'unknown' };
+    }
+    const rest = uri.slice(`${URI_SCHEME}://`.length);
+    if (rest === 'overview')
+        return { scheme: URI_SCHEME, kind: 'overview' };
+    if (rest === 'agent-instructions') {
+        return { scheme: URI_SCHEME, kind: 'agent-instructions' };
+    }
+    const [kind, ...rest2] = rest.split('/');
+    if (kind === 'knowledge' && rest2.length > 0) {
+        return { scheme: URI_SCHEME, kind: 'knowledge', id: decodeURIComponent(rest2.join('/')) };
+    }
+    if (kind === 'template' && rest2.length > 0) {
+        return { scheme: URI_SCHEME, kind: 'template', id: decodeURIComponent(rest2.join('/')) };
+    }
+    if (kind === 'docs' && rest2.length > 0) {
+        return {
+            scheme: URI_SCHEME,
+            kind: 'docs',
+            path: rest2.map(decodeURIComponent).join('/'),
+        };
+    }
+    return { scheme: URI_SCHEME, kind: 'unknown' };
+}

package/dist/server/create-mcp-server.d.ts

@@ -0,0 +1,55 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { type ISharkcraftInspection } from '@shrkcrft/inspector';
+import { type IMcpServerConfig } from './mcp-server-config.js';
+import type { IToolDefinition, McpGateResolver } from './tool-definition.js';
+export interface StartMcpServerOptions {
+    /** Working directory for SharkCraft project detection. */
+    cwd?: string;
+    /** Alias for cwd. If both are given, projectRoot wins. */
+    projectRoot?: string;
+    verbose?: boolean;
+    /** Watch sharkcraft/ for changes and emit resources/list_changed. */
+    watch?: boolean;
+    /**
+     * Transport selection.
+     * - 'stdio' (default) wires stdin/stdout (Claude Code style).
+     * - 'http' starts a Streamable-HTTP server on host/port.
+     */
+    transport?: 'stdio' | 'http';
+    /** HTTP host (when transport='http'). */
+    host?: string;
+    /** HTTP port (when transport='http'). */
+    port?: number;
+    /**
+     * Tier gate resolver. When provided, every CallTool invocation
+     * is consulted against the gate before the tool's handler runs. A
+     * non-null return blocks the call with the structured not-enabled
+     * error (mirrors the CLI behavior). Pass `null` for an open server.
+     */
+    gateResolver?: McpGateResolver;
+}
+export interface CreateSharkcraftServerOptions extends IMcpServerConfig {
+    /** Alias for cwd. If both are given, projectRoot wins. */
+    projectRoot?: string;
+    /** See {@link StartMcpServerOptions.gateResolver}. */
+    gateResolver?: McpGateResolver;
+}
+interface ServerState {
+    config: IMcpServerConfig;
+    inspection: ISharkcraftInspection | null;
+    toolsByName: Map<string, IToolDefinition>;
+    /** Optional tier-gate resolver. */
+    gateResolver?: McpGateResolver;
+}
+/**
+ * Resolve which directory the MCP server should treat as the target project.
+ * Priority: explicit option > SHARKCRAFT_PROJECT_ROOT env > process.cwd().
+ */
+export declare function resolveTargetRoot(optionCwd: string | undefined, optionProjectRoot: string | undefined, env?: Record<string, string | undefined>): string;
+export declare function createSharkcraftServer(config: CreateSharkcraftServerOptions): {
+    server: Server;
+    state: ServerState;
+};
+export declare function startMcpServer(options?: StartMcpServerOptions): Promise<void>;
+export {};
+//# sourceMappingURL=create-mcp-server.d.ts.map

package/dist/server/create-mcp-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-mcp-server.d.ts","sourceRoot":"","sources":["../../src/server/create-mcp-server.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AAQnE,OAAO,EAAqB,KAAK,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAEpF,OAAO,EAGL,KAAK,gBAAgB,EACtB,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EACV,eAAe,EAEf,eAAe,EAChB,MAAM,sBAAsB,CAAC;AAK9B,MAAM,WAAW,qBAAqB;IACpC,0DAA0D;IAC1D,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,0DAA0D;IAC1D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,qEAAqE;IACrE,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;;;;OAIG;IACH,SAAS,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IAC7B,yCAAyC;IACzC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,yCAAyC;IACzC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,YAAY,CAAC,EAAE,eAAe,CAAC;CAChC;AAED,MAAM,WAAW,6BAA8B,SAAQ,gBAAgB;IACrE,0DAA0D;IAC1D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,sDAAsD;IACtD,YAAY,CAAC,EAAE,eAAe,CAAC;CAChC;AAED,UAAU,WAAW;IACnB,MAAM,EAAE,gBAAgB,CAAC;IACzB,UAAU,EAAE,qBAAqB,GAAG,IAAI,CAAC;IACzC,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IAC1C,mCAAmC;IACnC,YAAY,CAAC,EAAE,eAAe,CAAC;CAChC;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,iBAAiB,EAAE,MAAM,GAAG,SAAS,EACrC,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAe,GACpD,MAAM,CAIR;AAqBD,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,6BAA6B,GAAG;IAC7E,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,WAAW,CAAC;CACpB,CAqHA;AAED,wBAAsB,cAAc,CAAC,OAAO,GAAE,qBAA0B,GAAG,OAAO,CAAC,IAAI,CAAC,CA0EvF"}

package/dist/server/create-mcp-server.js

@@ -0,0 +1,209 @@
+import * as nodePath from 'node:path';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema, ReadResourceRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { inspectSharkcraft } from '@shrkcrft/inspector';
+import { initTokenizer } from '@shrkcrft/context';
+import { MCP_SERVER_NAME, MCP_SERVER_VERSION, } from "./mcp-server-config.js";
+import { ALL_TOOLS } from "../tools/index.js";
+import { validateToolInput } from "./tool-input-validators.js";
+import { buildResourceList, readResource } from "../resources/index.js";
+/**
+ * Resolve which directory the MCP server should treat as the target project.
+ * Priority: explicit option > SHARKCRAFT_PROJECT_ROOT env > process.cwd().
+ */
+export function resolveTargetRoot(optionCwd, optionProjectRoot, env = process.env) {
+    const raw = optionProjectRoot ?? optionCwd ?? env.SHARKCRAFT_PROJECT_ROOT ?? process.cwd();
+    return nodePath.resolve(raw);
+}
+async function loadInspection(state) {
+    if (state.inspection)
+        return state.inspection;
+    state.inspection = await inspectSharkcraft({ cwd: state.config.cwd });
+    return state.inspection;
+}
+function toolResponseToCallResult(response) {
+    const content = [];
+    if (response.text)
+        content.push({ type: 'text', text: response.text });
+    if (response.data !== undefined) {
+        content.push({ type: 'text', text: JSON.stringify(response.data, null, 2) });
+    }
+    if (content.length === 0)
+        content.push({ type: 'text', text: '(empty)' });
+    return { content, isError: response.isError ?? false };
+}
+export function createSharkcraftServer(config) {
+    const resolvedCwd = resolveTargetRoot(config.cwd, config.projectRoot);
+    const effectiveConfig = {
+        name: config.name,
+        version: config.version,
+        cwd: resolvedCwd,
+        verbose: config.verbose,
+    };
+    const state = {
+        config: effectiveConfig,
+        inspection: null,
+        toolsByName: new Map(ALL_TOOLS.map((t) => [t.name, t])),
+        ...(config.gateResolver ? { gateResolver: config.gateResolver } : {}),
+    };
+    const server = new Server({ name: effectiveConfig.name, version: effectiveConfig.version }, {
+        capabilities: {
+            tools: {},
+            resources: { listChanged: true },
+        },
+    });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: ALL_TOOLS.map((t) => ({
+            name: t.name,
+            description: t.description,
+            inputSchema: t.inputSchema,
+        })),
+    }));
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const name = request.params.name;
+        const args = (request.params.arguments ?? {});
+        const tool = state.toolsByName.get(name);
+        if (!tool) {
+            return {
+                content: [{ type: 'text', text: `Unknown tool: ${name}` }],
+                isError: true,
+            };
+        }
+        // Tier gate. When the host wires a gateResolver, an
+        // experimental tool refuses with the same structured error the
+        // CLI emits. Bootstrap tools (no `cliCommand` field) always
+        // pass through.
+        if (state.gateResolver) {
+            const decision = state.gateResolver(tool);
+            if (decision) {
+                const body = {
+                    schema: 'sharkcraft.surface.not-enabled.v1',
+                    command: decision.command,
+                    tier: 'experimental',
+                    reason: decision.reason ??
+                        `MCP tool ${name} is gated: its CLI sibling \`${decision.command}\` is experimental and not enabled.`,
+                    enableCommand: `shrk surface enable ${decision.command}`,
+                    explainCommand: `shrk surface explain ${decision.command}`,
+                };
+                return {
+                    content: [
+                        { type: 'text', text: body.reason },
+                        { type: 'text', text: JSON.stringify(body, null, 2) },
+                    ],
+                    isError: true,
+                };
+            }
+        }
+        const validation = validateToolInput(name, args);
+        if (!validation.ok) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Invalid input for "${name}": ${validation.failure.message}`,
+                    },
+                    {
+                        type: 'text',
+                        text: JSON.stringify({ issues: validation.failure.issues }, null, 2),
+                    },
+                ],
+                isError: true,
+            };
+        }
+        try {
+            const inspection = await loadInspection(state);
+            const response = await tool.handler(validation.data, { inspection, cwd: state.config.cwd });
+            return toolResponseToCallResult(response);
+        }
+        catch (e) {
+            const message = e instanceof Error ? e.message : String(e);
+            return {
+                content: [{ type: 'text', text: `Tool "${name}" failed: ${message}` }],
+                isError: true,
+            };
+        }
+    });
+    server.setRequestHandler(ListResourcesRequestSchema, async () => {
+        const inspection = await loadInspection(state);
+        return { resources: buildResourceList(inspection) };
+    });
+    server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+        const inspection = await loadInspection(state);
+        const result = readResource(inspection, request.params.uri);
+        if (!result.ok) {
+            throw new Error(result.error);
+        }
+        return { contents: result.contents };
+    });
+    return { server, state };
+}
+export async function startMcpServer(options = {}) {
+    const cwd = resolveTargetRoot(options.cwd, options.projectRoot);
+    const verbose = options.verbose ?? false;
+    // Best-effort upgrade from the estimator to gpt-tokenizer. Failure leaves
+    // the estimator active — the server still serves requests.
+    if (process.env.SHARKCRAFT_NO_REAL_TOKENIZER !== '1') {
+        initTokenizer().catch(() => undefined);
+    }
+    const { server, state } = createSharkcraftServer({
+        name: MCP_SERVER_NAME,
+        version: MCP_SERVER_VERSION,
+        cwd,
+        verbose,
+        ...(options.gateResolver ? { gateResolver: options.gateResolver } : {}),
+    });
+    // Pre-warm inspection so the first tools/call is fast.
+    loadInspection(state).catch(() => undefined);
+    if (verbose) {
+        process.stderr.write(`[mcp] SharkCraft MCP server starting (cwd=${cwd})\n`);
+        process.stderr.write(`[mcp] Tools (${ALL_TOOLS.length}): ${ALL_TOOLS.map((t) => t.name).join(', ')}\n`);
+    }
+    // Optional watch — invalidates the inspection cache and notifies clients.
+    let watcher = null;
+    if (options.watch) {
+        const { startSharkcraftWatcher } = await import("./sharkcraft-watcher.js");
+        watcher = startSharkcraftWatcher({
+            cwd,
+            onChange: async () => {
+                state.inspection = null;
+                try {
+                    await server.sendResourceListChanged();
+                    if (verbose)
+                        process.stderr.write('[mcp] resources/list_changed sent\n');
+                }
+                catch (e) {
+                    if (verbose) {
+                        process.stderr.write(`[mcp] notify failed: ${e.message}\n`);
+                    }
+                }
+            },
+            log: (line) => verbose && process.stderr.write(`[mcp:watch] ${line}\n`),
+        });
+    }
+    const transportKind = options.transport ?? 'stdio';
+    if (transportKind === 'http') {
+        const { startHttpServer } = await import("./http-transport.js");
+        const handle = await startHttpServer({
+            server,
+            host: options.host,
+            port: options.port,
+            log: (line) => verbose && process.stderr.write(line + '\n'),
+        });
+        // Keep process alive until SIGINT/SIGTERM, then close.
+        const stop = async () => {
+            watcher?.stop();
+            await handle.close();
+            process.exit(0);
+        };
+        process.on('SIGINT', () => void stop());
+        process.on('SIGTERM', () => void stop());
+        // Always announce the URL on stderr so the user knows where to connect.
+        process.stderr.write(`[mcp] http endpoint: ${handle.url}\n`);
+        return;
+    }
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    if (verbose)
+        process.stderr.write('[mcp] connected via stdio\n');
+}