@adaptivemcp/spec 0.1.0

package/dist/events.d.ts

@@ -0,0 +1,15 @@
+import type { ToolExecutionEvent, ToolStatus } from "./types.js";
+export declare const TOOL_EXECUTION_EVENT: "dev.adaptivemcp/telemetry/tool.execution";
+export interface ToolEventContext {
+    toolName: string;
+    serverName?: string;
+    sessionId?: string;
+    requestId?: string;
+    model?: string;
+}
+/**
+ * Construct a tool execution event with sensible defaults. Timestamps use the
+ * ISO-8601 format; identifiers use a UUID v4 when not supplied.
+ */
+export declare function createToolEvent(ctx: ToolEventContext, status: ToolStatus, extra?: Partial<ToolExecutionEvent>): ToolExecutionEvent;
+//# sourceMappingURL=events.d.ts.map

package/dist/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAEjE,eAAO,MAAM,oBAAoB,EAAG,0CAAmD,CAAC;AAExF,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,GAAG,EAAE,gBAAgB,EACrB,MAAM,EAAE,UAAU,EAClB,KAAK,GAAE,OAAO,CAAC,kBAAkB,CAAM,GACtC,kBAAkB,CAYpB"}

package/dist/events.js

@@ -0,0 +1,19 @@
+export const TOOL_EXECUTION_EVENT = "dev.adaptivemcp/telemetry/tool.execution";
+/**
+ * Construct a tool execution event with sensible defaults. Timestamps use the
+ * ISO-8601 format; identifiers use a UUID v4 when not supplied.
+ */
+export function createToolEvent(ctx, status, extra = {}) {
+    return {
+        id: extra.id ?? crypto.randomUUID(),
+        toolName: ctx.toolName,
+        serverName: ctx.serverName,
+        sessionId: ctx.sessionId,
+        requestId: ctx.requestId,
+        model: ctx.model,
+        timestamp: extra.timestamp ?? new Date().toISOString(),
+        status,
+        ...extra,
+    };
+}
+//# sourceMappingURL=events.js.map

package/dist/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,oBAAoB,GAAG,0CAAmD,CAAC;AAUxF;;;GAGG;AACH,MAAM,UAAU,eAAe,CAC7B,GAAqB,EACrB,MAAkB,EAClB,QAAqC,EAAE;IAEvC,OAAO;QACL,EAAE,EAAE,KAAK,CAAC,EAAE,IAAI,MAAM,CAAC,UAAU,EAAE;QACnC,QAAQ,EAAE,GAAG,CAAC,QAAQ;QACtB,UAAU,EAAE,GAAG,CAAC,UAAU;QAC1B,SAAS,EAAE,GAAG,CAAC,SAAS;QACxB,SAAS,EAAE,GAAG,CAAC,SAAS;QACxB,KAAK,EAAE,GAAG,CAAC,KAAK;QAChB,SAAS,EAAE,KAAK,CAAC,SAAS,IAAI,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACtD,MAAM;QACN,GAAG,KAAK;KACT,CAAC;AACJ,CAAC"}

package/dist/extensions.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Identifiers for Adaptive MCP.
+ *
+ * MCP formalizes the server contract; the client side is loosely specified.
+ * Adaptive MCP's learning machinery runs on the client, which MCP does not
+ * govern. Therefore only ONE surface is proposed as a real MCP extension
+ * (SEP-2133): the `tools-metadata` resource a server publishes so clients can
+ * read learned tool metadata. See `docs/sep-2133-tools-metadata.md`.
+ *
+ * The remaining entries are internal, reversed-domain identifiers for the
+ * client-side packages. They follow the SEP-2133 naming convention (reversed
+ * domain `dev.adaptivemcp` owned by the author) but are NOT advertised as MCP
+ * extensions — they are namespacing for in-process concepts, not protocol
+ * extensions.
+ */
+export declare const EXTENSION_NAMESPACE = "dev.adaptivemcp/";
+/** The single proposed MCP extension (SEP-2133): a server-published resource. */
+export declare const TOOLS_METADATA_EXTENSION = "dev.adaptivemcp/tools-metadata";
+/**
+ * Internal reversed-domain identifiers for client-side packages. These are NOT
+ * MCP extensions; they namespace in-process concepts to avoid collisions.
+ */
+export declare const PACKAGE_IDENTIFIERS: {
+    readonly telemetry: "dev.adaptivemcp/telemetry";
+    readonly insights: "dev.adaptivemcp/insights";
+    readonly evaluation: "dev.adaptivemcp/evaluation";
+    readonly memory: "dev.adaptivemcp/memory";
+    readonly routing: "dev.adaptivemcp/routing";
+    readonly orchestration: "dev.adaptivemcp/orchestration";
+    readonly approval: "dev.adaptivemcp/approval";
+};
+export type PackageIdentifierName = keyof typeof PACKAGE_IDENTIFIERS;
+export declare function isExtensionIdentifier(value: string): boolean;
+export declare function packageIdentifier(name: PackageIdentifierName): string;
+//# sourceMappingURL=extensions.d.ts.map

package/dist/extensions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extensions.d.ts","sourceRoot":"","sources":["../src/extensions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,eAAO,MAAM,mBAAmB,qBAAqB,CAAC;AAEtD,iFAAiF;AACjF,eAAO,MAAM,wBAAwB,mCAAmC,CAAC;AAEzE;;;GAGG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;CAQtB,CAAC;AAEX,MAAM,MAAM,qBAAqB,GAAG,MAAM,OAAO,mBAAmB,CAAC;AAErE,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAE5D;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,qBAAqB,GAAG,MAAM,CAErE"}

package/dist/extensions.js

@@ -0,0 +1,38 @@
+/**
+ * Identifiers for Adaptive MCP.
+ *
+ * MCP formalizes the server contract; the client side is loosely specified.
+ * Adaptive MCP's learning machinery runs on the client, which MCP does not
+ * govern. Therefore only ONE surface is proposed as a real MCP extension
+ * (SEP-2133): the `tools-metadata` resource a server publishes so clients can
+ * read learned tool metadata. See `docs/sep-2133-tools-metadata.md`.
+ *
+ * The remaining entries are internal, reversed-domain identifiers for the
+ * client-side packages. They follow the SEP-2133 naming convention (reversed
+ * domain `dev.adaptivemcp` owned by the author) but are NOT advertised as MCP
+ * extensions — they are namespacing for in-process concepts, not protocol
+ * extensions.
+ */
+export const EXTENSION_NAMESPACE = "dev.adaptivemcp/";
+/** The single proposed MCP extension (SEP-2133): a server-published resource. */
+export const TOOLS_METADATA_EXTENSION = "dev.adaptivemcp/tools-metadata";
+/**
+ * Internal reversed-domain identifiers for client-side packages. These are NOT
+ * MCP extensions; they namespace in-process concepts to avoid collisions.
+ */
+export const PACKAGE_IDENTIFIERS = {
+    telemetry: "dev.adaptivemcp/telemetry",
+    insights: "dev.adaptivemcp/insights",
+    evaluation: "dev.adaptivemcp/evaluation",
+    memory: "dev.adaptivemcp/memory",
+    routing: "dev.adaptivemcp/routing",
+    orchestration: "dev.adaptivemcp/orchestration",
+    approval: "dev.adaptivemcp/approval",
+};
+export function isExtensionIdentifier(value) {
+    return typeof value === "string" && value.startsWith(EXTENSION_NAMESPACE);
+}
+export function packageIdentifier(name) {
+    return PACKAGE_IDENTIFIERS[name];
+}
+//# sourceMappingURL=extensions.js.map

package/dist/extensions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extensions.js","sourceRoot":"","sources":["../src/extensions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,MAAM,CAAC,MAAM,mBAAmB,GAAG,kBAAkB,CAAC;AAEtD,iFAAiF;AACjF,MAAM,CAAC,MAAM,wBAAwB,GAAG,gCAAgC,CAAC;AAEzE;;;GAGG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG;IACjC,SAAS,EAAE,2BAA2B;IACtC,QAAQ,EAAE,0BAA0B;IACpC,UAAU,EAAE,4BAA4B;IACxC,MAAM,EAAE,wBAAwB;IAChC,OAAO,EAAE,yBAAyB;IAClC,aAAa,EAAE,+BAA+B;IAC9C,QAAQ,EAAE,0BAA0B;CAC5B,CAAC;AAIX,MAAM,UAAU,qBAAqB,CAAC,KAAa;IACjD,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,UAAU,CAAC,mBAAmB,CAAC,CAAC;AAC5E,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,IAA2B;IAC3D,OAAO,mBAAmB,CAAC,IAAI,CAAC,CAAC;AACnC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./types.js";
+export * from "./extensions.js";
+export * from "./events.js";
+export { SPEC_VERSION } from "./version.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,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC"}

package/dist/index.js

@@ -0,0 +1,5 @@
+export * from "./types.js";
+export * from "./extensions.js";
+export * from "./events.js";
+export { SPEC_VERSION } from "./version.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Shared interfaces for Adaptive MCP.
+ *
+ * These types describe the application-level boundaries Adaptive MCP operates on.
+ * They intentionally avoid coupling to shell commands, filesystems, processes,
+ * sockets, or HTTP requests — those remain implementation details of MCP servers.
+ */
+export type ToolStatus = "started" | "completed" | "failed" | "cancelled";
+export interface CostInfo {
+    inputTokens?: number;
+    outputTokens?: number;
+    currency?: string;
+    amount?: number;
+}
+export interface ToolError {
+    message: string;
+    code?: string;
+}
+/**
+ * A single observation of a tool execution. This is the atomic unit of the
+ * observation layer and feeds telemetry, evaluation, and memory.
+ */
+export interface ToolExecutionEvent {
+    id: string;
+    toolName: string;
+    serverName?: string;
+    sessionId?: string;
+    requestId?: string;
+    timestamp: string;
+    durationMs?: number;
+    status: ToolStatus;
+    input?: unknown;
+    output?: unknown;
+    error?: ToolError;
+    model?: string;
+    cost?: CostInfo;
+    metadata?: Record<string, unknown>;
+}
+export type InsightSource = "telemetry" | "evaluation" | "human" | "memory";
+/**
+ * Learned metadata about a tool. Unlike static annotations, insights are
+ * derived from observed behavior and carry a confidence score.
+ */
+export interface Insight {
+    toolName: string;
+    key: string;
+    value: unknown;
+    confidence: number;
+    source: InsightSource;
+    observedAt: string;
+    sampleSize?: number;
+}
+export type RiskLevel = "low" | "medium" | "high";
+/**
+ * Written metadata attached to a tool by a human or operator.
+ */
+export interface Annotation {
+    toolName: string;
+    risk?: RiskLevel;
+    owner?: string;
+    tags?: string[];
+    description?: string;
+    metadata?: Record<string, unknown>;
+}
+export type RecommendationType = "model" | "approval" | "workflow" | "routing";
+/**
+ * A suggested adaptation derived from accumulated knowledge.
+ */
+export interface Recommendation {
+    toolName: string;
+    type: RecommendationType;
+    payload: unknown;
+    rationale: string;
+    confidence: number;
+    generatedAt: string;
+}
+/**
+ * The single source of truth (SSOT) record for a tool, persisted in SQLite.
+ * The YAML tools-metadata view is derived from this record.
+ */
+export interface ToolRecord {
+    toolName: string;
+    serverName?: string;
+    annotation: Annotation;
+    insights: Insight[];
+    recommendations: Recommendation[];
+    stats: ToolStats;
+    updatedAt: string;
+}
+export interface ToolStats {
+    invocations: number;
+    failures: number;
+    failureRate: number;
+    avgDurationMs: number | null;
+    totalCost: number;
+    lastObservedAt: string | null;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,9 @@
+/**
+ * Shared interfaces for Adaptive MCP.
+ *
+ * These types describe the application-level boundaries Adaptive MCP operates on.
+ * They intentionally avoid coupling to shell commands, filesystems, processes,
+ * sockets, or HTTP requests — those remain implementation details of MCP servers.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

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

package/dist/version.d.ts

@@ -0,0 +1,2 @@
+export declare const SPEC_VERSION = "0.1.0";
+//# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,YAAY,UAAU,CAAC"}

package/dist/version.js

@@ -0,0 +1,2 @@
+export const SPEC_VERSION = "0.1.0";
+//# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,YAAY,GAAG,OAAO,CAAC"}

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@adaptivemcp/spec",
+  "version": "0.1.0",
+  "description": "Extension identifiers, event schemas, and shared types for Adaptive 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"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run --config ../../vitest.config.ts"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  }
+}