@foro-sh/foro 0.14.0 → 0.16.0

package/README.md

@@ -2,6 +2,26 @@
 
 This package is the TypeScript SDK for Foro.
 
+## `skills(server, dir = 'skills')`
+
+Serves every `<dir>/<name>/SKILL.md` as an
+[Agent Skill over MCP](https://modelcontextprotocol.io/extensions/skills/overview):
+the `io.modelcontextprotocol/skills` capability, `skills/list` and `skills/get`
+with a SHA-256 manifest per skill, and each file over `resources/read` at
+`skill://<name>/<file>`.
+
+```ts
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { skills } from '@foro-sh/foro'
+
+const server = new McpServer({ name: 'my-server', version: '0.1.0' })
+skills(server) // before server.connect()
+```
+
+Needs `@modelcontextprotocol/sdk` 1.31+ and `zod` 4 alongside it. The
+directory is scanned once per process, and a skill whose frontmatter `name`
+isn't its directory name throws at startup rather than being served.
+
 ## `@foro-sh/foro/manifest-cases`
 
 The shared project-config validation table, as typed data. Foro's Python

package/dist/index.d.ts

@@ -1,2 +1,3 @@
 export declare function helloForo(name?: string): string;
+export { skills, SKILLS_EXTENSION, type SkillEntry } from "./skills.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,wBAAgB,SAAS,CAAC,IAAI,GAAE,MAAgB,GAAG,MAAM,CAExD"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,wBAAgB,SAAS,CAAC,IAAI,GAAE,MAAgB,GAAG,MAAM,CAExD;AACD,OAAO,EAAE,MAAM,EAAE,gBAAgB,EAAE,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -1,3 +1,4 @@
 export function helloForo(name = "world") {
     return `Hello, ${name} from Foro`;
 }
+export { skills, SKILLS_EXTENSION } from "./skills.js";

package/dist/manifest-cases.d.ts

@@ -1,27 +1,8 @@
-/**
- * The shared project-config validation table.
- *
- * foro's `_manifest.py` is a port of foro-sh/platform's
- * `apps/api/src/services/manifest.ts`, and the two can never be allowed to
- * silently disagree about what a valid manifest is - if they do, `foro check`
- * passes locally and the deploy fails, which is the exact gap this SDK exists
- * to close. Both sides therefore run the same table: the Python package
- * through `tests/test_manifest_cases.py`, the platform by importing
- * `manifestCases` from here (foro-sh/foro#5).
- *
- * The cases assert only accept/reject and the rejection reason - the resolved
- * defaults each implementation produces stay covered by its own tests.
- */
-/** Mirrors `ManifestRejectionReason` in foro-sh/platform's `@foro/types`.
- *  Kept in sync deliberately: it is what makes a reason added on one side a
- *  compile error on the other. */
+/** Shared project-config validation table. Imported by foro-sh/platform. */
+/** Mirrors `ManifestRejectionReason` in foro-sh/platform's `@foro/types`. */
 export type ManifestRejectionReason = 'missing_manifest' | 'unsupported_language' | 'invalid_yaml' | 'invalid_shape' | 'invalid_name' | 'invalid_entrypoint' | 'invalid_build_path' | 'invalid_runtime' | 'invalid_runtime_version' | 'invalid_port' | 'invalid_dependency_manager' | 'unsupported_project' | 'unknown_field' | 'invalid_egress';
 export interface ManifestCase {
-    /** Stable identifier, unique across the table - use it as the test name. */
     readonly name: string;
-    /** Files to write into an empty directory before validating it, keyed by
-     *  repo-relative path. Always the config file under test, plus whatever the
-     *  entry-file inference has to find on disk. */
     readonly files: Readonly<Record<string, string>>;
     readonly expect: {
         readonly ok: true;

package/dist/manifest-cases.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"manifest-cases.d.ts","sourceRoot":"","sources":["../src/manifest-cases.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH;;kCAEkC;AAClC,MAAM,MAAM,uBAAuB,GAC/B,kBAAkB,GAClB,sBAAsB,GACtB,cAAc,GACd,eAAe,GACf,cAAc,GACd,oBAAoB,GACpB,oBAAoB,GACpB,iBAAiB,GACjB,yBAAyB,GACzB,cAAc,GACd,4BAA4B,GAC5B,qBAAqB,GACrB,eAAe,GACf,gBAAgB,CAAA;AAEpB,MAAM,WAAW,YAAY;IAC3B,4EAA4E;IAC5E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB;;oDAEgD;IAChD,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;IAChD,QAAQ,CAAC,MAAM,EACX;QAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAA;KAAE,GACrB;QAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,uBAAuB,CAAA;KAAE,CAAA;CACrE;AAED,eAAO,MAAM,aAAa,EAAE,SAAS,YAAY,EAAqB,CAAA"}
+{"version":3,"file":"manifest-cases.d.ts","sourceRoot":"","sources":["../src/manifest-cases.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAI5E,6EAA6E;AAC7E,MAAM,MAAM,uBAAuB,GAC/B,kBAAkB,GAClB,sBAAsB,GACtB,cAAc,GACd,eAAe,GACf,cAAc,GACd,oBAAoB,GACpB,oBAAoB,GACpB,iBAAiB,GACjB,yBAAyB,GACzB,cAAc,GACd,4BAA4B,GAC5B,qBAAqB,GACrB,eAAe,GACf,gBAAgB,CAAA;AAEpB,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;IAChD,QAAQ,CAAC,MAAM,EACX;QAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAA;KAAE,GACrB;QAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,uBAAuB,CAAA;KAAE,CAAA;CACrE;AAED,eAAO,MAAM,aAAa,EAAE,SAAS,YAAY,EAAqB,CAAA"}

package/dist/manifest-cases.js

@@ -1,16 +1,3 @@
-/**
- * The shared project-config validation table.
- *
- * foro's `_manifest.py` is a port of foro-sh/platform's
- * `apps/api/src/services/manifest.ts`, and the two can never be allowed to
- * silently disagree about what a valid manifest is - if they do, `foro check`
- * passes locally and the deploy fails, which is the exact gap this SDK exists
- * to close. Both sides therefore run the same table: the Python package
- * through `tests/test_manifest_cases.py`, the platform by importing
- * `manifestCases` from here (foro-sh/foro#5).
- *
- * The cases assert only accept/reject and the rejection reason - the resolved
- * defaults each implementation produces stay covered by its own tests.
- */
+/** Shared project-config validation table. Imported by foro-sh/platform. */
 import { rawManifestCases } from './_generated-manifest-cases.js';
 export const manifestCases = rawManifestCases;

package/dist/skills.d.ts

@@ -0,0 +1,18 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare const SKILLS_EXTENSION = "io.modelcontextprotocol/skills";
+export interface SkillEntry {
+    uri: string;
+    frontmatter: Record<string, unknown>;
+    resources: {
+        uri: string;
+        digest: string;
+        size: number;
+    }[];
+}
+/** Serve every `<dir>/<name>/SKILL.md` as an MCP skill (SEP-2640): the
+ *  `io.modelcontextprotocol/skills` capability, `skills/list` and `skills/get`
+ *  with a SHA-256 manifest per skill, and each file over `resources/read` at
+ *  `skill://<name>/<path>`. Call before `connect`. Throws rather than serving a
+ *  skill a host would reject. */
+export declare function skills(server: McpServer, dir?: string): void;
+//# sourceMappingURL=skills.d.ts.map

package/dist/skills.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skills.d.ts","sourceRoot":"","sources":["../src/skills.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAA;AAKxE,eAAO,MAAM,gBAAgB,mCAAmC,CAAA;AAchE,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,MAAM,CAAA;IACX,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACpC,SAAS,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAA;CAC3D;AAiBD;;;;iCAIiC;AACjC,wBAAgB,MAAM,CAAC,MAAM,EAAE,SAAS,EAAE,GAAG,SAAW,GAAG,IAAI,CA+B9D"}

package/dist/skills.js

@@ -0,0 +1,131 @@
+import { isUtf8 } from 'node:buffer';
+import { createHash } from 'node:crypto';
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { extname, join, relative, resolve, sep } from 'node:path';
+import { McpError, ErrorCode, RequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { parse } from 'yaml';
+import { z } from 'zod';
+export const SKILLS_EXTENSION = 'io.modelcontextprotocol/skills';
+// Manifests are computed once from the files on disk, so an entry stays valid
+// for as long as the process does. Five minutes is the spec's own example;
+// nothing here is per-user, hence public.
+const CACHE = { ttlMs: 300_000, cacheScope: 'public' };
+const ListSkillsSchema = RequestSchema.extend({ method: z.literal('skills/list') });
+const GetSkillSchema = RequestSchema.extend({
+    method: z.literal('skills/get'),
+    params: z.looseObject({ uri: z.string() }),
+});
+// A stateless server builds a fresh McpServer per request, so the scan (and
+// every digest) is done once per directory rather than on every call.
+const scanned = new Map();
+/** Serve every `<dir>/<name>/SKILL.md` as an MCP skill (SEP-2640): the
+ *  `io.modelcontextprotocol/skills` capability, `skills/list` and `skills/get`
+ *  with a SHA-256 manifest per skill, and each file over `resources/read` at
+ *  `skill://<name>/<path>`. Call before `connect`. Throws rather than serving a
+ *  skill a host would reject. */
+export function skills(server, dir = 'skills') {
+    const root = resolve(dir);
+    let found = scanned.get(root);
+    if (!found) {
+        found = scan(root);
+        scanned.set(root, found);
+    }
+    const byUri = new Map(found.map((skill) => [skill.entry.uri, skill.entry]));
+    const listing = found.map((skill) => skill.entry);
+    server.server.registerCapabilities({ resources: {}, extensions: { [SKILLS_EXTENSION]: {} } });
+    // ponytail: one page, every skill. Fine at a handful; add a cursor when a
+    // server ships enough that one response gets heavy.
+    server.server.setRequestHandler(ListSkillsSchema, () => ({
+        resultType: 'complete',
+        skills: listing,
+        ...CACHE,
+    }));
+    server.server.setRequestHandler(GetSkillSchema, (request) => {
+        const entry = byUri.get(request.params.uri);
+        if (!entry)
+            throw new McpError(ErrorCode.InvalidParams, `Unknown skill: ${request.params.uri}`);
+        return { resultType: 'complete', skill: entry, ...CACHE };
+    });
+    for (const skill of found) {
+        for (const file of skill.files) {
+            server.registerResource(file.uri, file.uri, { mimeType: mimeType(file) }, () => ({
+                contents: [content(file)],
+            }));
+        }
+    }
+}
+function scan(root) {
+    let names;
+    try {
+        names = readdirSync(root).sort();
+    }
+    catch {
+        throw new Error(`skills: no skills directory at ${root}`);
+    }
+    const found = names
+        .filter((name) => statSync(join(root, name)).isDirectory())
+        .filter((name) => statSync(join(root, name, 'SKILL.md'), { throwIfNoEntry: false })?.isFile())
+        .map((name) => load(join(root, name), name));
+    if (found.length === 0)
+        throw new Error(`skills: no <name>/SKILL.md under ${root}`);
+    return found;
+}
+function load(dir, name) {
+    const main = join(dir, 'SKILL.md');
+    const frontmatter = parseFrontmatter(readFileSync(main, 'utf8'));
+    if (!frontmatter?.description) {
+        throw new Error(`skills: ${main} needs frontmatter with a name and a description`);
+    }
+    if (frontmatter.name !== name) {
+        throw new Error(`skills: ${main} is named ${JSON.stringify(frontmatter.name)}; ` +
+            `a skill's name must match its directory, ${JSON.stringify(name)}`);
+    }
+    // SKILL.md first, as the spec's examples list it.
+    const paths = [main, ...walk(dir).filter((path) => path !== main).sort()];
+    const files = paths.map((path) => {
+        const bytes = readFileSync(path);
+        return {
+            uri: `skill://${name}/${relative(dir, path).split(sep).join('/')}`,
+            digest: `sha256:${createHash('sha256').update(bytes).digest('hex')}`,
+            size: bytes.length,
+            bytes,
+        };
+    });
+    return {
+        entry: {
+            uri: `skill://${name}/SKILL.md`,
+            frontmatter,
+            resources: files.map(({ uri, digest, size }) => ({ uri, digest, size })),
+        },
+        files,
+    };
+}
+function parseFrontmatter(text) {
+    const match = /^\uFEFF?---\r?\n([\s\S]*?)\r?\n---\r?\n/.exec(text);
+    const parsed = match ? parse(match[1]) : undefined;
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed)
+        ? parsed
+        : undefined;
+}
+// Regular files only: a symlink could point outside the skill, and serving it
+// would publish whatever it points at.
+function walk(dir) {
+    return readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
+        const path = join(dir, entry.name);
+        if (entry.isDirectory())
+            return walk(path);
+        return entry.isFile() ? [path] : [];
+    });
+}
+function mimeType(file) {
+    if (!isUtf8(file.bytes))
+        return 'application/octet-stream';
+    return extname(file.uri) === '.md' ? 'text/markdown' : 'text/plain';
+}
+function content(file) {
+    // Text only when it round-trips: a host checks the digest against the bytes
+    // it reassembles, and a lossy decode would fail that check.
+    return isUtf8(file.bytes)
+        ? { uri: file.uri, mimeType: mimeType(file), text: file.bytes.toString('utf8') }
+        : { uri: file.uri, mimeType: mimeType(file), blob: file.bytes.toString('base64') };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@foro-sh/foro",
-    "version": "0.14.0",
+    "version": "0.16.0",
     "description": "TypeScript SDK for Foro",
     "type": "module",
     "main": "dist/index.js",
@@ -48,7 +48,24 @@
         "node": ">=18"
     },
     "devDependencies": {
+        "@modelcontextprotocol/sdk": "^1.31.0",
         "@types/node": "^26.2.0",
-        "typescript": "^7.0.2"
+        "typescript": "^7.0.2",
+        "zod": "^4.6.5"
+    },
+    "peerDependencies": {
+        "@modelcontextprotocol/sdk": "^1.31.0",
+        "zod": "^4.0.0"
+    },
+    "dependencies": {
+        "yaml": "^2.9.1"
+    },
+    "peerDependenciesMeta": {
+        "@modelcontextprotocol/sdk": {
+            "optional": true
+        },
+        "zod": {
+            "optional": true
+        }
     }
 }