@afora/mcp 0.0.0-stage → 0.0.4

package/dist/process.d.ts

@@ -0,0 +1,12 @@
+export interface RunResult {
+    readonly code: number | null;
+    readonly output: string;
+    /** The command could not be started. */
+    readonly missing: boolean;
+    readonly timedOut: boolean;
+}
+/** Runs a command, collecting stdout and stderr; never rejects. */
+export declare function run(command: string, args: readonly string[], options: {
+    cwd: string;
+    timeoutMs: number;
+}): Promise<RunResult>;

package/dist/server.d.ts

@@ -0,0 +1,18 @@
+import { type ProviderCatalogEntry, type StageCatalogEntry } from "@afora/codegen";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+export interface ServerOptions {
+    /** The project directory; every write stays inside it. The current directory by default. */
+    readonly project?: string;
+    /** `src/app.ts#App`: an application to extract the spec from when there is no afora.json. */
+    readonly app?: string;
+    /** External providers the spec's `provider.use` may name; `inMemory` is built in. */
+    readonly providers?: readonly ProviderCatalogEntry[];
+    /** External stages an output's `pipe` may name; `select` and `openapi` are built in. */
+    readonly stages?: readonly StageCatalogEntry[];
+}
+/**
+ * An MCP server for the project: tools to read, edit, validate and generate
+ * its afora.json, and resources with the schema, the catalog and a guide.
+ * Connect it to any transport.
+ */
+export declare function createServer(options?: ServerOptions): Promise<Server>;

package/dist/sink.d.ts

@@ -0,0 +1,83 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+/** The options of the `mcpTools` sink. JSON, so the stage can live in an `afora.json`. */
+export interface McpToolsOptions {
+    /** Name of the MCP server that `server()` creates. */
+    readonly name: string;
+    /** Version of the MCP server that `server()` creates. */
+    readonly version: string;
+    /** Prepended to every tool name, e.g. `"blog_"`. Empty by default. */
+    readonly prefix?: string;
+    /** Operation ids to expose (`"Users.register"`); every operation when omitted. */
+    readonly include?: readonly string[];
+    /**
+     * The context of an operation, by key: `{ token: "authorization" }` fills
+     * `context.token` from the value named `authorization` in the `extra` of
+     * the call (`extra.values`). A missing value leaves the key out.
+     */
+    readonly context?: {
+        readonly [contextKey: string]: string;
+    };
+}
+/** One MCP tool: what `tools/list` returns for it. */
+export interface McpToolDefinition {
+    readonly name: string;
+    readonly description: string;
+    /** JSON Schema of the operation input: an inline object, with no `$ref`. */
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly [key: string]: unknown;
+    };
+    /** The operation id the tool runs (`"Users.register"`). */
+    readonly operation: string;
+}
+/**
+ * What the host knows about a call. `values` feeds the `context` mapping of
+ * the options; `register` fills it from the HTTP headers (lower-case names)
+ * and the string entries of the request `_meta`.
+ */
+export interface McpCallExtra {
+    readonly values?: Readonly<Record<string, string | undefined>>;
+}
+/** The result of a tool call, as MCP expects it. */
+export interface McpToolResult {
+    readonly isError?: true;
+    readonly content: readonly {
+        readonly type: "text";
+        readonly text: string;
+    }[];
+}
+/** What the `mcpTools` sink builds. */
+export interface McpTools {
+    readonly tools: readonly McpToolDefinition[];
+    /** Runs a tool. Never throws: an unknown tool or an error is `isError: true`. */
+    call(name: string, args?: unknown, extra?: McpCallExtra): Promise<McpToolResult>;
+    /** Handles `tools/list` and `tools/call` on a low-level MCP SDK `Server`. */
+    register(server: Server): Server;
+    /** A new `Server` (capability `tools`) with the tools registered. */
+    server(): Server;
+}
+/**
+ * MCP tools for the operations, one per operation, named
+ * `{prefix}{command}_{operation}` in snake case (`users_register`).
+ *
+ * - `inputSchema` is the JSON Schema of the operation input (inline).
+ * - A call runs `operation.invoke(args, { context })`. The context comes from
+ *   `extra.values` through the `context` option; richer rules, such as
+ *   authentication, are a `transform` stage that wraps `invoke`.
+ * - Success is one text content with the response as JSON (`outputValueOf`:
+ *   sensitive values masked). An error is `isError: true` with the
+ *   `problemOf` JSON as text, whose `status` is the one of `statusOf`
+ *   (the output `statuses` first); invalid input is a 400 with `issues`.
+ * - The result has `tools`, `call(name, args, extra)`, `register(server)`
+ *   (handlers on a low-level SDK `Server`) and `server()` (a ready one).
+ */
+export declare const mcpTools: import("@afora/core").SinkFactory<McpTools, McpToolsOptions>;
+/** The runtime catalog of this module: the stage name `mcpTools` resolves to the sink. */
+export declare const McpStages: import("@afora/core").IStageCatalog<Readonly<Record<string, import("@afora/core").StageFactory>>>;
+/** The catalog entries codegen reads (`--stages @afora/mcp`). */
+export declare const stages: readonly [{
+    readonly name: "mcpTools";
+    readonly module: "@afora/mcp";
+    readonly export: "mcpTools";
+    readonly kind: "sink";
+}];

package/dist/spec-file.d.ts

@@ -0,0 +1,24 @@
+import { type CodegenOptions, type ProviderCatalogEntry, type ResolvedSpec, type Spec, type SpecIssue, type StageCatalogEntry } from "@afora/codegen";
+export interface Project {
+    /** The real path of the project directory. */
+    readonly root: string;
+    /** `src/app.ts#App`: where to extract the spec from when there is no afora.json. */
+    readonly app?: string;
+    /** External providers `use` may name in the spec (`inMemory` is built in). */
+    readonly providers?: readonly ProviderCatalogEntry[];
+    /** External stages an output's `pipe` may name (`select` and `openapi` are built in). */
+    readonly stages?: readonly StageCatalogEntry[];
+}
+/** What codegen needs from the project besides the spec. */
+export declare function codegenOptionsOf(project: Project): CodegenOptions;
+/** The project directory, resolved; it must exist. */
+export declare function openProject(directory: string, app?: string, providers?: readonly ProviderCatalogEntry[], stages?: readonly StageCatalogEntry[]): Promise<Project>;
+/** The spec on disk, or undefined when there is none. */
+export declare function readSpec(project: Project): Promise<Spec | undefined>;
+/** Writes the spec, tab-indented with its keys in a stable order. Confined to the project. */
+export declare function writeSpec(project: Project, spec: Spec): Promise<void>;
+/** Validates `spec` as the project's, resolving what it extends. */
+export declare function validateInProject(project: Project, spec: unknown): Promise<{
+    issues: SpecIssue[];
+    extended: Record<string, ResolvedSpec>;
+}>;

package/dist/tools.d.ts

@@ -0,0 +1,12 @@
+import { type Project } from "./spec-file.js";
+type Json = Record<string, unknown>;
+/** A tool: the name and description an agent sees, the JSON Schema of its input and its handler. */
+export interface ToolDefinition {
+    readonly name: string;
+    readonly description: string;
+    readonly inputSchema: Json;
+    readonly readOnly: boolean;
+    handle(args: Json, project: Project): Promise<unknown>;
+}
+export declare const tools: readonly ToolDefinition[];
+export {};

package/dist/typecheck.d.ts

@@ -0,0 +1,28 @@
+export interface Diagnostic {
+    readonly file: string;
+    readonly line: number;
+    readonly column: number;
+    readonly code: string;
+    readonly message: string;
+}
+export type TypecheckResult = {
+    readonly ran: true;
+    /** No diagnostic in the generated files. */
+    readonly ok: boolean;
+    /** Only the diagnostics of generated files are listed. */
+    readonly diagnostics: readonly Diagnostic[];
+    /** How many errors the rest of the project has (not listed). */
+    readonly otherErrors: number;
+} | {
+    readonly ran: false;
+    readonly reason: string;
+};
+/** Parses the output of `tsc --noEmit` (default, non-pretty format). */
+export declare function parseDiagnostics(output: string): (Diagnostic & {
+    readonly path: string;
+})[];
+/**
+ * Runs `tsc --noEmit -p <root>` when the project has a tsconfig.json, and
+ * keeps only the diagnostics of `files` (paths relative to `root`).
+ */
+export declare function typecheck(root: string, files: readonly string[]): Promise<TypecheckResult>;

package/package.json

@@ -1,6 +1,63 @@
 {
-  "name": "@afora/mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@afora/mcp",
+	"version": "0.0.4",
+	"description": "An MCP server that lets an agent discover the afora catalog, edit afora.json, validate it, generate the code and check the result.",
+	"keywords": [
+		"afora",
+		"mcp",
+		"model-context-protocol",
+		"codegen",
+		"agents"
+	],
+	"author": "Alan Reis <alanreisanjo@gmail.com> (https://github.com/Hoyasumii)",
+	"license": "MIT",
+	"homepage": "https://github.com/afora-framework/core/tree/main/packages/mcp#readme",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/afora-framework/core.git",
+		"directory": "packages/mcp"
+	},
+	"type": "module",
+	"main": "./dist/index.js",
+	"module": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js",
+			"default": "./dist/index.js"
+		},
+		"./package.json": "./package.json"
+	},
+	"files": [
+		"dist"
+	],
+	"bin": {
+		"afora-mcp": "dist/bin.js"
+	},
+	"engines": {
+		"bun": ">=1.4.4",
+		"node": ">=22"
+	},
+	"publishConfig": {
+		"access": "public",
+		"provenance": true
+	},
+	"scripts": {
+		"typecheck": "bun check",
+		"build": "rm -rf dist && bun build ./src/index.ts ./src/bin.ts ./src/extract-child.ts --outdir ./dist --target node --format esm --packages external --tsconfig-override tsconfig.build.json && tsc -p tsconfig.build.json && bun ../../scripts/add-dts-extensions.ts dist",
+		"test": "bun test"
+	},
+	"dependencies": {
+		"@afora/codegen": "^0.0.4",
+		"@modelcontextprotocol/sdk": "^1.32.0"
+	},
+	"devDependencies": {
+		"@types/bun": "^1.4.4",
+		"typebox": "^1.4.3"
+	},
+	"peerDependencies": {
+		"@afora/core": ">=0.0.1",
+		"typebox": "^1"
+	}
+}