@savvy-web/mcp 0.3.0 → 0.4.0

package/547.js

@@ -1,416 +0,0 @@
-import { ChangesetConfigReaderLive, SilkWorkspaceAnalyzer, SilkWorkspaceAnalyzerLive, TagStrategyLive, VersioningStrategyLive } from "@savvy-web/silk-effects";
-import { Effect, JSONSchema, Layer, ParseResult, Schema } from "effect";
-import { WorkspaceRoot, WorkspaceRootLive, WorkspacesLive } from "workspaces-effect";
-import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { z } from "zod";
-import { existsSync, readFileSync } from "node:fs";
-import { dirname, isAbsolute, join, normalize, resolve, sep } from "node:path";
-import { fileURLToPath } from "node:url";
-const DepsLive = Layer.mergeAll(WorkspacesLive, ChangesetConfigReaderLive, TagStrategyLive, VersioningStrategyLive.pipe(Layer.provide(ChangesetConfigReaderLive)));
-const SilkRuntimeLive = Layer.mergeAll(SilkWorkspaceAnalyzerLive, WorkspaceRootLive).pipe(Layer.provide(DepsLive));
-const TIER_HEADINGS = [
-    [
-        "standards",
-        "Standards"
-    ],
-    [
-        "packages",
-        "Packages"
-    ],
-    [
-        "guides",
-        "Guides"
-    ]
-];
-function renderCatalogMarkdown(manifest) {
-    const lines = [
-        "# silk://catalog",
-        "",
-        "Read this first to orient. To fetch a doc, call `resources/read` with its `silk://` URI.",
-        "To search by intent, use the `silk_docs_search` tool.",
-        ""
-    ];
-    for (const [tier, heading] of TIER_HEADINGS){
-        const entries = manifest.entries.filter((e)=>e.tier === tier && "deprecated" !== e.status);
-        if (0 !== entries.length) {
-            lines.push(`## ${heading}`, "");
-            for (const e of entries){
-                const gen = "generated" === e.source ? " (generated)" : "";
-                lines.push(`- \`${e.uri}\`${gen} — ${e.title}. load when: ${e.summary}`);
-            }
-            lines.push("");
-        }
-    }
-    return lines.join("\n");
-}
-function resolveResourcePath(root, relativePath) {
-    if (relativePath.includes("\0")) throw new Error("path contains null byte");
-    if (isAbsolute(relativePath)) throw new Error("absolute path not allowed");
-    const stripped = relativePath.replace(/^\/+/, "");
-    const withIndex = "" === stripped || stripped.endsWith("/") ? `${stripped}index` : stripped;
-    const withExt = withIndex.endsWith(".md") ? withIndex : `${withIndex}.md`;
-    const resolved = resolve(root, normalize(withExt));
-    const rootWithSep = root.endsWith(sep) ? root : `${root}${sep}`;
-    if (!resolved.startsWith(rootWithSep) && resolved !== root) throw new Error("path escapes content root");
-    return resolved;
-}
-const ID_PATTERN = /^(standards|packages|guides)\/[A-Za-z0-9._-]+(?:\/[A-Za-z0-9._-]+)*\/?$/;
-const Tier = Schema.Literal("standards", "packages", "guides");
-const Audience = Schema.Array(Schema.Literal("user", "assistant"));
-const Source = Schema.Literal("hand", "generated");
-const Status = Schema.Literal("draft", "stable", "deprecated");
-const DocFrontMatter = Schema.Struct({
-    id: Schema.String.pipe(Schema.pattern(ID_PATTERN)),
-    title: Schema.NonEmptyString,
-    summary: Schema.NonEmptyString,
-    tier: Tier,
-    source: Source,
-    status: Schema.optionalWith(Status, {
-        default: ()=>"stable"
-    }),
-    supersededBy: Schema.optional(Schema.String),
-    tags: Schema.Array(Schema.NonEmptyString),
-    audience: Schema.optionalWith(Audience, {
-        default: ()=>[
-                "assistant"
-            ]
-    }),
-    priority: Schema.optionalWith(Schema.Number.pipe(Schema.between(0, 1)), {
-        default: ()=>0.5
-    }),
-    related: Schema.optionalWith(Schema.Array(Schema.String), {
-        default: ()=>[]
-    })
-});
-const ManifestEntry = Schema.Struct({
-    ...DocFrontMatter.fields,
-    uri: Schema.String,
-    lastModified: Schema.optional(Schema.String)
-});
-const Manifest = Schema.Struct({
-    entries: Schema.Array(ManifestEntry)
-});
-Schema.decodeUnknown(DocFrontMatter);
-Schema.decodeUnknown(Manifest);
-function resolveContentRoot() {
-    const here = dirname(fileURLToPath(import.meta.url));
-    const candidates = [
-        join(here, "resources", "content"),
-        join(here, "..", "resources", "content"),
-        join(here, "content")
-    ];
-    for (const candidate of candidates)if (existsSync(join(candidate, "manifest.json"))) return candidate;
-    throw new Error(`[savvy-mcp] cannot locate resources/content with a manifest.json (tried: ${candidates.join(", ")})`);
-}
-function loadManifest(contentRoot) {
-    const raw = JSON.parse(readFileSync(join(contentRoot, "manifest.json"), "utf8"));
-    return Schema.decodeUnknownSync(Manifest)(raw);
-}
-function readDocBody(contentRoot, relPath) {
-    return readFileSync(resolveResourcePath(contentRoot, relPath), "utf8");
-}
-const resourceName = (entry)=>`silk_${entry.id.replace(/[^A-Za-z0-9]/g, "_")}`;
-const toSdkAnnotations = (e)=>({
-        audience: [
-            ...e.audience
-        ],
-        priority: e.priority,
-        ...e.lastModified ? {
-            lastModified: e.lastModified
-        } : {}
-    });
-function registerAllResources(server, deps) {
-    const { manifest, bodies, contentRoot } = deps;
-    server.registerResource("silk_catalog", "silk://catalog", {
-        title: "Silk resource catalog",
-        description: "Read this first. Lists every Silk resource grouped by tier with a 'load when' hint. Fetch a doc with resources/read <uri>; search by intent with silk_docs_search.",
-        mimeType: "text/markdown"
-    }, async (uri)=>({
-            contents: [
-                {
-                    uri: uri.href,
-                    mimeType: "text/markdown",
-                    text: renderCatalogMarkdown(manifest)
-                }
-            ]
-        }));
-    const byUri = new Map(manifest.entries.map((e)=>[
-            e.uri,
-            e
-        ]));
-    const readBody = (uri, relPath)=>bodies ? bodies[uri] ?? "" : readDocBody(contentRoot, relPath);
-    server.registerResource("silk_doc", new ResourceTemplate("silk://{+path}", {
-        list: async ()=>({
-                resources: manifest.entries.filter((e)=>"deprecated" !== e.status).map((e)=>({
-                        name: resourceName(e),
-                        uri: e.uri,
-                        title: e.title,
-                        description: e.summary,
-                        mimeType: "text/markdown",
-                        annotations: toSdkAnnotations(e)
-                    }))
-            })
-    }), {
-        title: "Silk documentation resource",
-        mimeType: "text/markdown"
-    }, async (uri, variables)=>{
-        const relPath = String(variables.path ?? "");
-        const entry = byUri.get(uri.href);
-        return {
-            contents: [
-                {
-                    uri: uri.href,
-                    mimeType: "text/markdown",
-                    text: readBody(uri.href, relPath),
-                    ...entry ? {
-                        annotations: toSdkAnnotations(entry)
-                    } : {}
-                }
-            ]
-        };
-    });
-}
-function formatQueryLogLine(query, results) {
-    const top = results.slice(0, 3);
-    const belowThreshold = 0 === results.length || results.every((r)=>"low" === r.confidenceLabel);
-    const payload = {
-        query,
-        topResults: top.map((r)=>r.uri),
-        topConfidence: results[0]?.confidence ?? 0,
-        belowThreshold
-    };
-    return `[savvy-mcp] docs-search ${JSON.stringify(payload)}`;
-}
-const stderrQueryLogger = (line)=>{
-    process.stderr.write(`${line}\n`);
-};
-const effectToZodSchema = (schema)=>{
-    const jsonSchema = JSONSchema.make(schema);
-    const inlined = inlineAllRefs(jsonSchema);
-    const zodSchema = z.fromJSONSchema(inlined);
-    if (isObjectLike(zodSchema)) return zodSchema;
-    return z.object({}).catchall(z.unknown());
-};
-const isObjectLike = (schema)=>schema instanceof z.ZodObject;
-const REF_PREFIX = "#/$defs/";
-const inlineAllRefs = (root)=>{
-    const defs = root.$defs ?? {};
-    const visit = (value)=>{
-        if (Array.isArray(value)) return value.map(visit);
-        if (null === value || "object" != typeof value) return value;
-        const obj = value;
-        if ("string" == typeof obj.$ref && obj.$ref.startsWith(REF_PREFIX)) {
-            const defName = obj.$ref.slice(REF_PREFIX.length);
-            const target = defs[defName];
-            if (void 0 !== target) return visit(target);
-        }
-        const out = {};
-        for (const [k, v] of Object.entries(obj))if ("$defs" !== k) out[k] = visit(v);
-        return out;
-    };
-    return visit(root);
-};
-const DocsSearchHit = Schema.Struct({
-    uri: Schema.String,
-    title: Schema.String,
-    summary: Schema.String,
-    tags: Schema.Array(Schema.String),
-    tier: Schema.Literal("standards", "packages", "guides"),
-    confidence: Schema.Number,
-    confidenceLabel: Schema.Literal("high", "medium", "low"),
-    matchedOn: Schema.Array(Schema.String),
-    related: Schema.optionalWith(Schema.Array(Schema.String), {
-        default: ()=>[]
-    })
-}).annotations({
-    identifier: "DocsSearchHit"
-});
-const DocsSearchResult = Schema.Struct({
-    query: Schema.String,
-    results: Schema.Array(DocsSearchHit)
-}).annotations({
-    identifier: "DocsSearchResult",
-    title: "silk_docs_search result",
-    description: "Ranked Silk documentation matches. Fetch a hit with resources/read <uri>."
-});
-const formatDocsSearchMarkdown = (data)=>{
-    const lines = [
-        `# silk_docs_search: ${data.query}`,
-        ""
-    ];
-    if (0 === data.results.length) {
-        lines.push("No results. Read `silk://catalog` and select a doc by reasoning.");
-        return lines.join("\n");
-    }
-    const allLow = data.results.every((r)=>"low" === r.confidenceLabel);
-    if (allLow) lines.push("_No high-confidence match — read `silk://catalog` and pick by reasoning._", "");
-    for (const r of data.results)lines.push(`- \`${r.uri}\` (${r.confidenceLabel}) — ${r.title}. ${r.summary}`);
-    lines.push("", "Fetch any hit with `resources/read <uri>`.");
-    return lines.join("\n");
-};
-const DocsSearchResultAsMarkdown = Schema.transformOrFail(DocsSearchResult, Schema.String, {
-    strict: true,
-    decode: (data)=>ParseResult.succeed(formatDocsSearchMarkdown(data)),
-    encode: (text, _opts, ast)=>ParseResult.fail(new ParseResult.Forbidden(ast, text, "DocsSearchResultAsMarkdown is one-way."))
-});
-const runDocsSearch = (index, query, opts, logger)=>{
-    const results = index.search(query, opts);
-    if (logger) logger(formatQueryLogLine(query, results));
-    return {
-        query,
-        results
-    };
-};
-const WorkspaceSummary = Schema.Struct({
-    name: Schema.String,
-    version: Schema.String,
-    path: Schema.String,
-    root: Schema.Boolean,
-    publishable: Schema.Boolean,
-    targets: Schema.Array(Schema.String).annotations({
-        description: "Publish registry URLs."
-    }),
-    versioned: Schema.Boolean,
-    tagged: Schema.Boolean,
-    released: Schema.Boolean,
-    linked: Schema.Array(Schema.String).annotations({
-        description: "Names of linked workspaces."
-    }),
-    fixed: Schema.Array(Schema.String).annotations({
-        description: "Names of fixed-group siblings."
-    })
-}).annotations({
-    identifier: "WorkspaceSummary"
-});
-const WorkspaceInfoResult = Schema.Struct({
-    root: Schema.String,
-    runtime: Schema.Literal("node", "bun"),
-    packageManager: Schema.Struct({
-        type: Schema.Literal("npm", "pnpm", "yarn", "bun"),
-        version: Schema.optional(Schema.String)
-    }),
-    workspaceCount: Schema.Number,
-    workspaces: Schema.Array(WorkspaceSummary)
-}).annotations({
-    identifier: "WorkspaceInfoResult",
-    title: "workspace_info result",
-    description: "Structured snapshot of the Silk workspace: runtime, package manager, and a per-workspace summary (publishability, versioning, tag/release state, linked/fixed relations)."
-});
-const toSummary = (w)=>({
-        name: w.name,
-        version: w.version.current,
-        path: w.path,
-        root: w.root,
-        publishable: w.publishable,
-        targets: w.targets.map((t)=>t.registry),
-        versioned: w.versioned,
-        tagged: w.tagged,
-        released: w.released,
-        linked: w.linked.map((l)=>l.name),
-        fixed: w.fixed.map((f)=>f.name)
-    });
-const toWorkspaceInfoResult = (analysis)=>({
-        root: analysis.root,
-        runtime: analysis.runtime,
-        packageManager: {
-            type: analysis.packageManager.type,
-            ...void 0 !== analysis.packageManager.version ? {
-                version: analysis.packageManager.version
-            } : {}
-        },
-        workspaceCount: analysis.workspaces.length,
-        workspaces: analysis.workspaces.map(toSummary)
-    });
-const formatWorkspaceInfoMarkdown = (data)=>{
-    const pm = data.packageManager.version ? `${data.packageManager.type}@${data.packageManager.version}` : data.packageManager.type;
-    const lines = [
-        `# Workspace: ${data.root}`,
-        "",
-        `- runtime: ${data.runtime}`,
-        `- package manager: ${pm}`,
-        `- workspaces: ${data.workspaceCount}`,
-        "",
-        "| name | version | publishable | versioned | tagged | released |",
-        "| --- | --- | --- | --- | --- | --- |"
-    ];
-    for (const w of data.workspaces)lines.push(`| ${w.name} | ${w.version} | ${w.publishable} | ${w.versioned} | ${w.tagged} | ${w.released} |`);
-    return lines.join("\n");
-};
-const WorkspaceInfoAsMarkdown = Schema.transformOrFail(WorkspaceInfoResult, Schema.String, {
-    strict: true,
-    decode: (data)=>ParseResult.succeed(formatWorkspaceInfoMarkdown(data)),
-    encode: (text, _options, ast)=>ParseResult.fail(new ParseResult.Forbidden(ast, text, "WorkspaceInfoAsMarkdown is one-way: markdown cannot be parsed back."))
-});
-const workspaceInfo = (base)=>Effect.gen(function*() {
-        const workspaceRoot = yield* WorkspaceRoot;
-        const root = yield* workspaceRoot.find(base);
-        const analyzer = yield* SilkWorkspaceAnalyzer;
-        const analysis = yield* analyzer.analyze(root);
-        return toWorkspaceInfoResult(analysis);
-    });
-const structuredResult = (text, structured)=>({
-        content: [
-            {
-                type: "text",
-                text
-            }
-        ],
-        structuredContent: structured
-    });
-function buildServer(ctx) {
-    const server = new McpServer({
-        name: "savvy-mcp",
-        version: "0.0.0"
-    });
-    server.registerTool("workspace_info", {
-        description: "Use when you need the Silk workspace layout: runtime, package manager, and a per-workspace summary (publishability, versioning, tag/release state). Prefer this over running shell commands to inspect the workspace. Returns markdown in content[] and a typed object in structuredContent.",
-        inputSchema: {
-            cwd: z.optional(z.string()).describe("Workspace root to analyze. Defaults to the server's project dir.")
-        },
-        outputSchema: effectToZodSchema(WorkspaceInfoResult)
-    }, async (args)=>{
-        const root = args.cwd ?? ctx.cwd;
-        const data = await ctx.runtime.runPromise(workspaceInfo(root));
-        const text = Schema.decodeSync(WorkspaceInfoAsMarkdown)(data);
-        return structuredResult(text, data);
-    });
-    server.registerTool("silk_docs_search", {
-        description: "Search Silk documentation by intent. Pass plain keywords or a short phrase describing what you need (e.g. 'changeset bump rules'). Returns ranked docs with a confidence label; fetch a hit with resources/read <uri>. Read silk://catalog first to orient.",
-        inputSchema: {
-            query: z.string().describe("Keywords or a short phrase describing the doc you need."),
-            limit: z.optional(z.number()).describe("Max results (default 10)."),
-            tier: z.optional(z["enum"]([
-                "standards",
-                "packages",
-                "guides"
-            ])).describe("Restrict to one tier.")
-        },
-        outputSchema: effectToZodSchema(DocsSearchResult),
-        annotations: {
-            readOnlyHint: true
-        }
-    }, async (args)=>{
-        const data = runDocsSearch(ctx.docIndex, args.query, {
-            ...void 0 !== args.limit ? {
-                limit: args.limit
-            } : {},
-            ...void 0 !== args.tier ? {
-                tier: args.tier
-            } : {}
-        }, stderrQueryLogger);
-        const text = Schema.decodeSync(DocsSearchResultAsMarkdown)(data);
-        return structuredResult(text, data);
-    });
-    registerAllResources(server, {
-        manifest: ctx.manifest,
-        contentRoot: ctx.contentRoot
-    });
-    return server;
-}
-async function startMcpServer(ctx) {
-    const server = buildServer(ctx);
-    const transport = new StdioServerTransport();
-    await server.connect(transport);
-}
-export { SilkRuntimeLive, loadManifest, readDocBody, resolveContentRoot, startMcpServer };

package/index.d.ts

@@ -1,126 +0,0 @@
-/**
- * Public barrel for `@savvy-web/mcp`.
- *
- * @packageDocumentation
- */
-
-import { FileSystem } from '@effect/platform/FileSystem';
-import { Layer } from 'effect';
-import type { ManagedRuntime } from 'effect';
-import { Path } from '@effect/platform/Path';
-import { Schema } from 'effect';
-import { SilkWorkspaceAnalyzer } from '@savvy-web/silk-effects';
-import { WorkspaceDiscoveryError } from 'workspaces-effect';
-import { WorkspaceRoot } from 'workspaces-effect';
-
-/**
- * The package version, replaced at build time. `0.0.0` in dev/test indicates
- * an unbuilt source run. Kept in its own module so both `server.ts` and the
- * `index.ts` barrel can import it without forming an import cycle.
- *
- * @packageDocumentation
- */
-export declare const CURRENT_MCP_VERSION = "0.0.0";
-
-export declare class DocIndex {
-    private readonly fuse;
-    private readonly entries;
-    private readonly byUri;
-    private constructor();
-    static fromManifest(manifest: Manifest, bodies: Readonly<Record<string, string>>): DocIndex;
-    search(query: string, opts?: SearchOptions): SearchResult[];
-    /** Never return empty: surface the top entries (by priority) as low-confidence. */
-    private fallback;
-}
-
-export declare const Manifest: Schema.Struct<{
-    entries: Schema.Array$<Schema.Struct<{
-        id: Schema.filter<typeof Schema.String>;
-        title: typeof Schema.NonEmptyString;
-        summary: typeof Schema.NonEmptyString;
-        tier: Schema.Literal<["standards", "packages", "guides"]>;
-        source: Schema.Literal<["hand", "generated"]>;
-        status: Schema.optionalWith<Schema.Literal<["draft", "stable", "deprecated"]>, {
-            default: () => "stable";
-        }>;
-        supersededBy: Schema.optional<typeof Schema.String>;
-        tags: Schema.Array$<typeof Schema.NonEmptyString>;
-        audience: Schema.optionalWith<Schema.Array$<Schema.Literal<["user", "assistant"]>>, {
-            default: () => ReadonlyArray<"assistant">;
-        }>;
-        priority: Schema.optionalWith<Schema.filter<typeof Schema.Number>, {
-            default: () => number;
-        }>;
-        related: Schema.optionalWith<Schema.Array$<typeof Schema.String>, {
-            default: () => ReadonlyArray<string>;
-        }>;
-        uri: typeof Schema.String;
-        lastModified: Schema.optional<typeof Schema.String>;
-    }>>;
-}>;
-
-export declare type Manifest = Schema.Schema.Type<typeof Manifest>;
-
-/** A manifest entry = decoded front-matter + the derived uri + lastModified. */
-export declare const ManifestEntry: Schema.Struct<{
-    id: Schema.filter<typeof Schema.String>;
-    title: typeof Schema.NonEmptyString;
-    summary: typeof Schema.NonEmptyString;
-    tier: Schema.Literal<["standards", "packages", "guides"]>;
-    source: Schema.Literal<["hand", "generated"]>;
-    status: Schema.optionalWith<Schema.Literal<["draft", "stable", "deprecated"]>, {
-        default: () => "stable";
-    }>;
-    supersededBy: Schema.optional<typeof Schema.String>;
-    tags: Schema.Array$<typeof Schema.NonEmptyString>;
-    audience: Schema.optionalWith<Schema.Array$<Schema.Literal<["user", "assistant"]>>, {
-        default: () => ReadonlyArray<"assistant">;
-    }>;
-    priority: Schema.optionalWith<Schema.filter<typeof Schema.Number>, {
-        default: () => number;
-    }>;
-    related: Schema.optionalWith<Schema.Array$<typeof Schema.String>, {
-        default: () => ReadonlyArray<string>;
-    }>;
-    uri: typeof Schema.String;
-    lastModified: Schema.optional<typeof Schema.String>;
-}>;
-
-export declare type ManifestEntry = Schema.Schema.Type<typeof ManifestEntry>;
-
-/** The long-lived runtime, the project working directory, and the resource layer. */
-export declare interface McpContext {
-    readonly runtime: ManagedRuntime.ManagedRuntime<SilkWorkspaceAnalyzer | WorkspaceRoot, WorkspaceDiscoveryError>;
-    readonly cwd: string;
-    readonly docIndex: DocIndex;
-    readonly manifest: Manifest;
-    readonly contentRoot: string;
-}
-
-export declare interface SearchOptions {
-    readonly limit?: number;
-    readonly tier?: ManifestEntry["tier"];
-}
-
-export declare interface SearchResult {
-    readonly uri: string;
-    readonly title: string;
-    readonly summary: string;
-    readonly tags: ReadonlyArray<string>;
-    readonly tier: ManifestEntry["tier"];
-    readonly confidence: number;
-    readonly confidenceLabel: "high" | "medium" | "low";
-    readonly matchedOn: ReadonlyArray<string>;
-    readonly related: ReadonlyArray<string>;
-}
-
-/**
- * The MCP runtime layer. Provides `SilkWorkspaceAnalyzer` and `WorkspaceRoot`;
- * requires `FileSystem` + `Path` from the host's platform layer.
- */
-export declare const SilkRuntimeLive: Layer.Layer<SilkWorkspaceAnalyzer | WorkspaceRoot, WorkspaceDiscoveryError, FileSystem | Path>;
-
-/** Build the server and connect it over stdio. */
-export declare function startMcpServer(ctx: McpContext): Promise<void>;
-
-export { }

package/index.js

@@ -1,3 +0,0 @@
-var src_CURRENT_MCP_VERSION = "0.0.0";
-export { SilkRuntimeLive, startMcpServer } from "./547.js";
-export { src_CURRENT_MCP_VERSION as CURRENT_MCP_VERSION };

package/tsdoc-metadata.json

@@ -1,11 +0,0 @@
-// This file is read by tools that parse documentation comments conforming to the TSDoc standard.
-// It should be published with your NPM package.  It should not be tracked by Git.
-{
-  "tsdocVersion": "0.12",
-  "toolPackages": [
-    {
-      "packageName": "@microsoft/api-extractor",
-      "packageVersion": "7.58.7"
-    }
-  ]
-}