somamcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Jordan
+
+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/dist/index.d.ts

@@ -0,0 +1,444 @@
+import { DirectLogger, DirectLogger as DirectLogger$1 } from "functype-log";
+import { Context as Context$1, Hono } from "hono";
+import { Tool as Tool$1 } from "@modelcontextprotocol/sdk/types.js";
+
+//#region src/artifacts/types.d.ts
+type StaticArtifact = {
+  contentType: string;
+  content: string;
+  path: string;
+  type: "static";
+};
+type DynamicArtifact = {
+  handler: (c: Context$1) => Response | Promise<Response>;
+  path: string;
+  type: "dynamic";
+};
+type DirectoryArtifact = {
+  directory: string;
+  path: string;
+  type: "directory";
+};
+type ArtifactConfig = DirectoryArtifact | DynamicArtifact | StaticArtifact;
+//#endregion
+//#region src/types/core.d.ts
+type SessionAuth = Record<string, unknown> | undefined;
+/**
+ * Structural type compatible with StandardSchemaV1 (zod, valibot, etc.)
+ * We define this structurally to avoid a direct dependency on @standard-schema/spec.
+ */
+type SchemaParams = {
+  readonly "~standard": {
+    readonly version: 1;
+    readonly vendor: string;
+    readonly types?: {
+      readonly input: unknown;
+      readonly output: unknown;
+    } | undefined;
+    readonly validate: (value: unknown) => {
+      value: unknown;
+    } | {
+      issues: ReadonlyArray<{
+        message: string;
+      }>;
+    };
+  };
+};
+type InferSchemaOutput<P extends SchemaParams> = NonNullable<P["~standard"]["types"]>["output"] extends infer O ? [O] extends [never] ? unknown : O : unknown;
+type TextContent = {
+  text: string;
+  type: "text";
+};
+type ImageContent = {
+  data: string;
+  mimeType: string;
+  type: "image";
+};
+type AudioContent = {
+  data: string;
+  mimeType: string;
+  type: "audio";
+};
+type ResourceContent = {
+  resource: {
+    blob?: string;
+    mimeType?: string;
+    text?: string;
+    uri: string;
+  };
+  type: "resource";
+};
+type ResourceLink = {
+  mimeType?: string;
+  name?: string;
+  type: "resource_link";
+  uri: string;
+};
+type Content = AudioContent | ImageContent | ResourceContent | ResourceLink | TextContent;
+type ContentResult = {
+  content: Content[];
+  isError?: boolean;
+};
+type Progress = {
+  progress: number;
+  total?: number;
+};
+type Context<T extends SessionAuth = SessionAuth> = {
+  client: {
+    version: unknown;
+  };
+  log: {
+    debug: (message: string, data?: unknown) => void;
+    error: (message: string, data?: unknown) => void;
+    info: (message: string, data?: unknown) => void;
+    warn: (message: string, data?: unknown) => void;
+  };
+  reportProgress: (progress: Progress) => Promise<void>;
+  requestId?: string;
+  session: T | undefined;
+  sessionId?: string;
+  streamContent: (content: Content | Content[]) => Promise<void>;
+};
+type ToolAnnotations = {
+  destructiveHint?: boolean;
+  idempotentHint?: boolean;
+  openWorldHint?: boolean;
+  readOnlyHint?: boolean;
+  streamingHint?: boolean;
+  title?: string;
+};
+type Tool<T extends SessionAuth = SessionAuth, P extends SchemaParams = SchemaParams> = {
+  _meta?: {
+    [key: string]: unknown;
+    ui?: {
+      resourceUri?: string;
+    };
+  };
+  annotations?: ToolAnnotations;
+  canAccess?: (auth: T) => boolean;
+  description?: string;
+  execute: (args: InferSchemaOutput<P>, context: Context<T>) => Promise<Content | ContentResult | string | void>;
+  name: string;
+  outputSchema?: SchemaParams;
+  parameters?: P;
+  timeoutMs?: number;
+};
+type Completion = {
+  hasMore?: boolean;
+  total?: number;
+  values: string[];
+};
+type ResourceResult = {
+  blob: string;
+  mimeType?: string;
+  uri?: string;
+} | {
+  mimeType?: string;
+  text: string;
+  uri?: string;
+};
+type Resource<T extends SessionAuth = SessionAuth> = {
+  complete?: (name: string, value: string, auth?: T) => Promise<Completion>;
+  description?: string;
+  load: (auth?: T) => Promise<ResourceResult | ResourceResult[]>;
+  mimeType?: string;
+  name: string;
+  uri: string;
+};
+type PromptArgument<T extends SessionAuth = SessionAuth> = Readonly<{
+  complete?: (value: string, auth?: T) => Promise<Completion>;
+  description?: string;
+  enum?: string[];
+  name: string;
+  required?: boolean;
+}>;
+type PromptResult = {
+  messages: unknown[];
+} | string;
+type Prompt<T extends SessionAuth = SessionAuth, Args extends PromptArgument<T>[] = PromptArgument<T>[]> = {
+  arguments?: Args;
+  complete?: (name: string, value: string, auth?: T) => Promise<Completion>;
+  description?: string;
+  load: (args: Record<string, string | undefined>, auth?: T) => Promise<PromptResult>;
+  name: string;
+};
+type ServerStatus = "error" | "running" | "stopped";
+declare class UserError extends Error {
+  constructor(message: string);
+}
+//#endregion
+//#region src/types/server.d.ts
+type Logger = {
+  debug: (...args: unknown[]) => void;
+  error: (...args: unknown[]) => void;
+  info: (...args: unknown[]) => void;
+  log: (...args: unknown[]) => void;
+  warn: (...args: unknown[]) => void;
+};
+type ServerConfig<T extends SessionAuth = SessionAuth> = {
+  authenticate?: (request: unknown) => Promise<T>;
+  instructions?: string;
+  logger?: Logger;
+  name: string;
+  version: `${number}.${number}.${number}`;
+};
+type TransportConfig = {
+  transportType: "stdio";
+} | {
+  httpStream: {
+    enableJsonResponse?: boolean;
+    endpoint?: `/${string}`;
+    host?: string;
+    port: number;
+  };
+  transportType: "httpStream";
+};
+//#endregion
+//#region src/backend/adapter.d.ts
+type BackendSession<T extends SessionAuth = SessionAuth> = {
+  sessionId?: string;
+  auth?: T;
+};
+type BackendEvents<T extends SessionAuth> = {
+  connect: (event: {
+    session: BackendSession<T>;
+  }) => void;
+  disconnect: (event: {
+    session: BackendSession<T>;
+  }) => void;
+};
+type BackendAdapter<T extends SessionAuth = SessionAuth> = {
+  readonly serverState: ServerStatus;
+  readonly sessions: ReadonlyArray<BackendSession<T>>;
+  addPrompt: <Args extends PromptArgument<T>[]>(prompt: Prompt<T, Args>) => void;
+  addResource: (resource: Resource<T>) => void;
+  addResourceTemplate: (...args: ReadonlyArray<unknown>) => void;
+  addTool: <P extends SchemaParams>(tool: Tool<T, P>) => void;
+  getApp: () => Hono;
+  on: <E extends keyof BackendEvents<T>>(event: E, handler: BackendEvents<T>[E]) => void;
+  removePrompt: (name: string) => void;
+  removeResource: (name: string) => void;
+  removeTool: (name: string) => void;
+  start: (transport?: TransportConfig) => Promise<void>;
+  stop: () => Promise<void>;
+};
+type BackendFactory<T extends SessionAuth = SessionAuth> = (config: {
+  authenticate?: (request: unknown) => Promise<T>;
+  instructions?: string;
+  name: string;
+  version: `${number}.${number}.${number}`;
+}, backendOptions?: Record<string, unknown>) => BackendAdapter<T>;
+//#endregion
+//#region src/gateway/types.d.ts
+type GatewayConfig = {
+  id: string;
+  name?: string;
+  proxyTools?: boolean;
+  reconnect?: boolean;
+  reconnectIntervalMs?: number;
+  toolPrefix?: string;
+  url: string;
+};
+type GatewayStatus = "connected" | "connecting" | "disconnected" | "error";
+type GatewayInfo = {
+  id: string;
+  name: string;
+  remoteTools: ReadonlyArray<{
+    description?: string;
+    name: string;
+  }>;
+  status: GatewayStatus;
+  url: string;
+};
+type GatewayInstance = {
+  readonly config: GatewayConfig;
+  readonly info: GatewayInfo;
+  readonly name: string;
+  readonly status: GatewayStatus;
+  readonly tools: ReadonlyArray<Tool$1>;
+  callTool: (name: string, args?: Record<string, unknown>) => Promise<unknown>;
+  connect: () => Promise<void>;
+  disconnect: () => Promise<void>;
+};
+type GatewayManagerInstance = {
+  readonly connectedCount: number;
+  readonly totalCount: number;
+  add: (config: GatewayConfig) => GatewayInstance;
+  connectAll: () => Promise<void>;
+  disconnectAll: () => Promise<void>;
+  get: (id: string) => GatewayInstance | undefined;
+  getAll: () => ReadonlyArray<GatewayInstance>;
+  getInfoAll: () => ReadonlyArray<GatewayInfo>;
+};
+//#endregion
+//#region src/telemetry/TelemetryCollector.d.ts
+type TelemetryEventType = "server.start" | "server.stop" | "tool.execute" | "tool.error" | "resource.load" | "resource.error" | "prompt.load" | "prompt.error" | "gateway.connect" | "gateway.disconnect" | "gateway.error" | "session.connect" | "session.disconnect";
+type ErrorCategory = "validation" | "timeout" | "gateway" | "internal" | "auth" | "not_found";
+type CaptureLevel = "full" | "metadata" | "none";
+type ToolCaptureConfig = {
+  captureLevel?: CaptureLevel;
+  maxOutputSize?: number;
+  redactInputFields?: ReadonlyArray<string>;
+};
+type TelemetryEvent = {
+  data?: Record<string, unknown>;
+  durationMs?: number;
+  error?: string;
+  errorCategory?: ErrorCategory;
+  errorStack?: string;
+  input?: Record<string, unknown>;
+  name: string;
+  output?: unknown;
+  requestId?: string;
+  sessionId?: string;
+  timestamp: number;
+  type: TelemetryEventType;
+};
+type TelemetryCollector = {
+  flush?: () => Promise<void>;
+  recordEvent: (event: TelemetryEvent) => void;
+};
+//#endregion
+//#region src/types.d.ts
+type SomaServerOptions<T extends SessionAuth = SessionAuth> = ServerConfig<T> & {
+  artifacts?: ArtifactConfig[];
+  backendOptions?: Record<string, unknown>;
+  enableDashboard?: boolean;
+  enableIntrospection?: boolean;
+  gateways?: GatewayConfig[];
+  logLayer?: DirectLogger$1;
+  telemetry?: TelemetryCollector;
+};
+type ServerHealth = {
+  activeSessions: number;
+  gateways: {
+    connected: number;
+    total: number;
+  };
+  name: string;
+  startedAt: number;
+  status: ServerStatus;
+  uptime: number;
+};
+type ServerCapabilities = {
+  prompts: ReadonlyArray<{
+    description?: string;
+    name: string;
+  }>;
+  resources: ReadonlyArray<{
+    description?: string;
+    name: string;
+    uri: string;
+  }>;
+  tools: ReadonlyArray<{
+    description?: string;
+    name: string;
+  }>;
+};
+type ToolOptions<T extends SessionAuth = SessionAuth, P extends SchemaParams = SchemaParams> = Tool<T, P> & {
+  captureConfig?: ToolCaptureConfig;
+};
+type SomaServerInstance<T extends SessionAuth = SessionAuth> = {
+  readonly name: string;
+  readonly serverState: ServerStatus;
+  readonly sessions: ReadonlyArray<BackendSession<T>>;
+  addPrompt: <Args extends PromptArgument<T>[]>(prompt: Prompt<T, Args>) => void;
+  addPrompts: <Args extends PromptArgument<T>[]>(prompts: Prompt<T, Args>[]) => void;
+  addResource: (resource: Resource<T>) => void;
+  addResources: (resources: Resource<T>[]) => void;
+  addResourceTemplate: (...args: ReadonlyArray<unknown>) => void;
+  addTool: <P extends SchemaParams>(tool: Tool<T, P>) => void;
+  addTools: <P extends SchemaParams>(tools: Tool<T, P>[]) => void;
+  getApp: () => Hono;
+  getCapabilities: () => ServerCapabilities;
+  getGatewayManager: () => GatewayManagerInstance;
+  getHealth: () => ServerHealth;
+  removePrompt: (name: string) => void;
+  removeResource: (name: string) => void;
+  removeTool: (name: string) => void;
+  start: (options?: TransportConfig) => Promise<void>;
+  stop: () => Promise<void>;
+};
+//#endregion
+//#region src/Server.d.ts
+declare const createServer: <T extends SessionAuth = SessionAuth>(options: SomaServerOptions<T>) => SomaServerInstance<T>;
+//#endregion
+//#region src/content/helpers.d.ts
+type ContentInput = {
+  buffer: Buffer;
+} | {
+  path: string;
+} | {
+  url: string;
+};
+declare const imageContent: (input: ContentInput) => Promise<ImageContent>;
+declare const audioContent: (input: ContentInput) => Promise<AudioContent>;
+//#endregion
+//#region src/backend/fastmcp.d.ts
+declare const createFastMCPBackend: <T extends SessionAuth = SessionAuth>(config: ServerConfig<T>, backendOptions?: Record<string, unknown>) => BackendAdapter<T>;
+//#endregion
+//#region src/telemetry/CompositeTelemetry.d.ts
+declare const createCompositeTelemetry: (collectors: ReadonlyArray<TelemetryCollector>) => TelemetryCollector;
+//#endregion
+//#region src/telemetry/ConsoleTelemetry.d.ts
+declare const createConsoleTelemetry: (prefix?: string) => TelemetryCollector;
+//#endregion
+//#region src/telemetry/EnrichedError.d.ts
+type EnrichedErrorResponse = {
+  errorCategory: ErrorCategory;
+  message: string;
+  relatedState?: Record<string, unknown>;
+  suggestions?: ReadonlyArray<string>;
+};
+declare const classifyError: (error: unknown) => ErrorCategory;
+declare const createEnrichedError: (error: unknown, context?: {
+  gatewayStatus?: string;
+  toolName?: string;
+}) => EnrichedErrorResponse;
+//#endregion
+//#region src/telemetry/JsonFileTelemetry.d.ts
+type JsonFileTelemetryOptions = {
+  filePath: string;
+  flushIntervalMs?: number;
+};
+declare const createJsonFileTelemetry: (options: JsonFileTelemetryOptions) => TelemetryCollector;
+//#endregion
+//#region src/telemetry/LogLayerTelemetry.d.ts
+declare const createLogLayerTelemetry: (logger: DirectLogger$1) => TelemetryCollector;
+//#endregion
+//#region src/telemetry/NoopTelemetry.d.ts
+declare const NoopTelemetry: TelemetryCollector;
+//#endregion
+//#region src/telemetry/telemetryWrapper.d.ts
+declare const wrapTool: <T extends SessionAuth, P extends SchemaParams>(tool: Tool<T, P>, telemetry: TelemetryCollector, captureConfig?: ToolCaptureConfig) => Tool<T, P>;
+declare const wrapResource: <T extends SessionAuth>(resource: Resource<T>, telemetry: TelemetryCollector) => Resource<T>;
+declare const wrapPrompt: <T extends SessionAuth, Args extends PromptArgument<T>[] = PromptArgument<T>[]>(prompt: Prompt<T, Args>, telemetry: TelemetryCollector) => Prompt<T, Args>;
+//#endregion
+//#region src/logging.d.ts
+declare const createDefaultLogger: (name: string) => DirectLogger$1;
+//#endregion
+//#region src/artifacts/ArtifactManager.d.ts
+declare const registerArtifacts: (app: Hono, artifacts: ReadonlyArray<ArtifactConfig>) => void;
+//#endregion
+//#region src/artifacts/DashboardArtifact.d.ts
+declare const createDashboardArtifact: (getHealth: () => ServerHealth, getCapabilities: () => ServerCapabilities, getConnections: () => ReadonlyArray<GatewayInfo>) => ArtifactConfig;
+//#endregion
+//#region src/introspection/capabilitiesTool.d.ts
+declare const createCapabilitiesTool: <T extends SessionAuth>(getCapabilities: () => ServerCapabilities) => Tool<T>;
+//#endregion
+//#region src/introspection/connectionsTool.d.ts
+declare const createConnectionsTool: <T extends SessionAuth>(getConnections: () => ReadonlyArray<GatewayInfo>) => Tool<T>;
+//#endregion
+//#region src/introspection/healthTool.d.ts
+declare const createHealthTool: <T extends SessionAuth>(getHealth: () => ServerHealth) => Tool<T>;
+//#endregion
+//#region src/gateway/Gateway.d.ts
+declare const createGateway: (config: GatewayConfig, telemetry: TelemetryCollector) => GatewayInstance;
+//#endregion
+//#region src/gateway/GatewayManager.d.ts
+declare const createGatewayManager: (telemetry: TelemetryCollector) => GatewayManagerInstance;
+//#endregion
+//#region src/gateway/toolProxy.d.ts
+declare const createProxiedTools: <T extends SessionAuth>(gateway: GatewayInstance, telemetry?: TelemetryCollector) => ReadonlyArray<Tool<T>>;
+//#endregion
+export { type ArtifactConfig, type AudioContent, type BackendAdapter, type BackendFactory, type BackendSession, type CaptureLevel, type Completion, type Content, type ContentResult, type Context, type DirectLogger, type DirectoryArtifact, type DynamicArtifact, type EnrichedErrorResponse, type ErrorCategory, type GatewayConfig, type GatewayInfo, type GatewayInstance, type GatewayManagerInstance, type GatewayStatus, type ImageContent, type InferSchemaOutput, type JsonFileTelemetryOptions, type Logger, NoopTelemetry, type Progress, type Prompt, type PromptArgument, type PromptResult, type Resource, type ResourceContent, type ResourceLink, type ResourceResult, type SchemaParams, type ServerCapabilities, type ServerConfig, type ServerHealth, type ServerStatus, type SessionAuth, type SomaServerInstance, type SomaServerOptions, type StaticArtifact, type TelemetryCollector, type TelemetryEvent, type TelemetryEventType, type TextContent, type Tool, type ToolAnnotations, type ToolCaptureConfig, type ToolOptions, type TransportConfig, UserError, audioContent, classifyError, createCapabilitiesTool, createCompositeTelemetry, createConnectionsTool, createConsoleTelemetry, createDashboardArtifact, createDefaultLogger, createEnrichedError, createFastMCPBackend, createGateway, createGatewayManager, createHealthTool, createJsonFileTelemetry, createLogLayerTelemetry, createProxiedTools, createServer, imageContent, registerArtifacts, wrapPrompt, wrapResource, wrapTool };

package/dist/index.js

@@ -0,0 +1,58 @@
+import{Ref as e,Try as t}from"functype";import{FastMCP as n,ServerState as r}from"fastmcp";import{Client as i}from"@modelcontextprotocol/sdk/client/index.js";import{StreamableHTTPClientTransport as a}from"@modelcontextprotocol/sdk/client/streamableHttp.js";import{appendFile as o,mkdir as s,readFile as c}from"node:fs/promises";import{dirname as l,extname as u}from"node:path";import{createDirectConsoleLogger as d}from"functype-log";const f=(e,t)=>{for(let n of t)switch(n.type){case`static`:e.get(n.path,e=>e.body(n.content,{headers:{"Content-Type":n.contentType}}));break;case`dynamic`:e.get(n.path,e=>n.handler(e));break;case`directory`:break}},p=(e,t,n)=>({handler:()=>{let r=m(e(),t(),n());return new Response(r,{headers:{"Content-Type":`text/html; charset=utf-8`}})},path:`/dashboard`,type:`dynamic`}),m=(e,t,n)=>`<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>${e.name} - SomaMCP Dashboard</title>
+  <style>
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    body { font-family: system-ui, -apple-system, sans-serif; background: #0a0a0a; color: #e0e0e0; padding: 2rem; }
+    h1 { font-size: 1.5rem; margin-bottom: 1.5rem; color: #fff; }
+    h2 { font-size: 1.1rem; margin-bottom: 0.75rem; color: #a0a0a0; text-transform: uppercase; letter-spacing: 0.05em; }
+    .grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(300px, 1fr)); gap: 1.5rem; }
+    .card { background: #1a1a1a; border: 1px solid #2a2a2a; border-radius: 8px; padding: 1.25rem; }
+    .status { display: inline-block; padding: 2px 8px; border-radius: 4px; font-size: 0.85rem; font-weight: 600; }
+    .status.running { background: #0a3d0a; color: #4ade80; }
+    .status.stopped { background: #3d0a0a; color: #f87171; }
+    .status.error { background: #3d2a0a; color: #fbbf24; }
+    .status.connected { background: #0a3d0a; color: #4ade80; }
+    .status.disconnected { background: #3d0a0a; color: #f87171; }
+    .metric { margin: 0.5rem 0; }
+    .metric-label { color: #888; font-size: 0.85rem; }
+    .metric-value { color: #fff; font-weight: 500; }
+    ul { list-style: none; }
+    li { padding: 0.35rem 0; border-bottom: 1px solid #222; font-size: 0.9rem; }
+    li:last-child { border-bottom: none; }
+    .desc { color: #888; font-size: 0.8rem; }
+  </style>
+</head>
+<body>
+  <h1>${e.name}</h1>
+  <div class="grid">
+    <div class="card">
+      <h2>Health</h2>
+      <div class="metric"><span class="metric-label">Status:</span> <span class="status ${e.status}">${e.status}</span></div>
+      <div class="metric"><span class="metric-label">Uptime:</span> <span class="metric-value">${h(e.uptime)}</span></div>
+      <div class="metric"><span class="metric-label">Sessions:</span> <span class="metric-value">${e.activeSessions}</span></div>
+      <div class="metric"><span class="metric-label">Gateways:</span> <span class="metric-value">${e.gateways.connected}/${e.gateways.total}</span></div>
+    </div>
+    <div class="card">
+      <h2>Tools (${t.tools.length})</h2>
+      <ul>${t.tools.map(e=>`<li><strong>${e.name}</strong>${e.description?` <span class="desc">${e.description}</span>`:``}</li>`).join(``)}</ul>
+    </div>
+    <div class="card">
+      <h2>Resources (${t.resources.length})</h2>
+      <ul>${t.resources.map(e=>`<li><strong>${e.name}</strong> <span class="desc">${e.uri}</span></li>`).join(``)}</ul>
+    </div>
+    <div class="card">
+      <h2>Prompts (${t.prompts.length})</h2>
+      <ul>${t.prompts.map(e=>`<li><strong>${e.name}</strong>${e.description?` <span class="desc">${e.description}</span>`:``}</li>`).join(``)}</ul>
+    </div>
+    ${n.length>0?`<div class="card">
+      <h2>Gateways (${n.length})</h2>
+      <ul>${n.map(e=>`<li><strong>${e.name}</strong> <span class="status ${e.status}">${e.status}</span> <span class="desc">${e.url}</span></li>`).join(``)}</ul>
+    </div>`:``}
+  </div>
+</body>
+</html>`,h=e=>{let t=Math.floor(e/1e3),n=Math.floor(t/60),r=Math.floor(n/60),i=Math.floor(r/24);return i>0?`${String(i)}d ${String(r%24)}h`:r>0?`${String(r)}h ${String(n%60)}m`:n>0?`${String(n)}m ${String(t%60)}s`:`${String(t)}s`},g=e=>{switch(e){case r.Running:return`running`;case r.Error:return`error`;default:return`stopped`}},_=(e,t)=>{let r=new n({...t,authenticate:e.authenticate,instructions:e.instructions,logger:e.logger,name:e.name,version:e.version});return{get serverState(){return g(r.serverState)},get sessions(){return r.sessions.map(e=>({sessionId:e.sessionId}))},addPrompt:e=>{r.addPrompt(e)},addResource:e=>{r.addResource(e)},addResourceTemplate:(...e)=>{r.addResourceTemplate(...e)},addTool:e=>{r.addTool(e)},getApp:()=>r.getApp(),on:(e,t)=>{r.on(e,t)},removePrompt:e=>r.removePrompt(e),removeResource:e=>r.removeResource(e),removeTool:e=>r.removeTool(e),start:async e=>{if(!e){await r.start();return}e.transportType===`httpStream`?await r.start({httpStream:e.httpStream,transportType:`httpStream`}):await r.start({transportType:`stdio`})},stop:()=>r.stop()}},v=(t,n)=>{let r=e(void 0),o=e(void 0),s=e([]),c=e(`disconnected`),l=e(void 0),u=t.name??t.id,d=()=>{let e=t.reconnectIntervalMs??5e3;l.set(setTimeout(()=>{f.connect()},e))},f={get config(){return t},get info(){return{id:t.id,name:u,remoteTools:s.get().map(e=>({description:e.description,name:e.name})),status:c.get(),url:t.url}},get name(){return u},get status(){return c.get()},get tools(){return s.get()},async callTool(e,n={}){let i=r.get();if(!i||c.get()!==`connected`)throw Error(`Gateway ${t.id} is not connected`);return await i.callTool({arguments:n,name:e})},async connect(){if(c.get()===`connected`)return;c.set(`connecting`);let e=Date.now();try{let l=new a(new URL(t.url));o.set(l);let d=new i({name:`soma-gateway-${t.id}`,version:`1.0.0`});r.set(d),await d.connect(l);let f=await d.listTools();s.set(f.tools),c.set(`connected`),n.recordEvent({data:{id:t.id,remoteToolCount:s.get().length,url:t.url},durationMs:Date.now()-e,name:u,timestamp:e,type:`gateway.connect`})}catch(r){c.set(`error`),n.recordEvent({data:{id:t.id,url:t.url},error:r instanceof Error?r.message:String(r),name:u,timestamp:e,type:`gateway.error`}),t.reconnect!==!1&&d()}},async disconnect(){let e=l.get();e&&(clearTimeout(e),l.set(void 0));let i=r.get();if(i)try{await i.close()}catch{}r.set(void 0),o.set(void 0),s.set([]),c.set(`disconnected`),n.recordEvent({data:{id:t.id},name:u,timestamp:Date.now(),type:`gateway.disconnect`})}};return f},y=e=>{let t=new Map;return{get connectedCount(){return[...t.values()].filter(e=>e.status===`connected`).length},get totalCount(){return t.size},add(n){let r=v(n,e);return t.set(n.id,r),r},async connectAll(){await Promise.allSettled([...t.values()].map(e=>e.connect()))},async disconnectAll(){await Promise.allSettled([...t.values()].map(e=>e.disconnect()))},get(e){return t.get(e)},getAll(){return[...t.values()]},getInfoAll(){return[...t.values()].map(e=>e.info)}}},b=e=>{if(e instanceof Error){let t=e.message.toLowerCase();if(t.includes(`validation`)||t.includes(`invalid`)||t.includes(`schema`))return`validation`;if(t.includes(`timeout`)||t.includes(`timed out`)||t.includes(`etimedout`))return`timeout`;if(t.includes(`gateway`)||t.includes(`not connected`)||t.includes(`econnrefused`)||t.includes(`connection refused`))return`gateway`;if(t.includes(`auth`)||t.includes(`unauthorized`)||t.includes(`forbidden`))return`auth`;if(t.includes(`not found`)||t.includes(`404`))return`not_found`}return typeof e==`object`&&e&&`name`in e&&e.name===`UserError`?`validation`:`internal`},x=(e,t)=>{switch(e){case`validation`:return[`Check the tool's parameter schema and provide valid input`];case`timeout`:return[`The operation timed out. Try again or reduce the scope of the request`];case`gateway`:return[`Gateway is ${t?.gatewayStatus??`unavailable`}. The remote service may be down`,`Try again later or check the remote service status`];case`auth`:return[`Authentication failed. Check credentials or permissions`];case`not_found`:return[`The requested resource was not found. Verify the identifier`];case`internal`:return[`An internal error occurred. The tool maintainer should investigate`]}},S=(e,t)=>{let n=b(e),r=e instanceof Error?e.message:String(e),i=x(n,t),a={...t?.gatewayStatus&&{gatewayStatus:t.gatewayStatus},...t?.toolName&&{toolName:t.toolName}};return{errorCategory:n,message:r,...Object.keys(a).length>0&&{relatedState:a},suggestions:i}},C=e=>t.fromPromise(e),w=(e,t)=>{let n=e.config.toolPrefix??`${e.config.id}_`;return e.tools.map(r=>({annotations:{openWorldHint:!0,readOnlyHint:!0},description:`[${e.name}] ${r.description??`Remote tool`}`,execute:async i=>{let a=Date.now(),o=`${n}${r.name}`;return(await C(e.callTool(r.name,i))).fold(n=>{let s=S(n,{gatewayStatus:e.status,toolName:r.name});return t?.recordEvent({data:{gateway:e.config.id,remoteTool:r.name},durationMs:Date.now()-a,error:s.message,errorCategory:s.errorCategory,errorStack:n.stack,input:i,name:o,timestamp:a,type:`tool.error`}),{content:[{text:JSON.stringify(s,null,2),type:`text`}],isError:!0}},n=>(t?.recordEvent({data:{gateway:e.config.id,remoteTool:r.name},durationMs:Date.now()-a,input:i,name:o,output:n,timestamp:a,type:`tool.execute`}),JSON.stringify(n,null,2)))},name:`${n}${r.name}`}))},T=e=>({annotations:{readOnlyHint:!0},description:`Lists all tools, resources, and prompts registered on this server`,execute:()=>Promise.resolve(JSON.stringify(e(),null,2)),name:`soma_capabilities`}),E=e=>({annotations:{readOnlyHint:!0},description:`Lists all gateway connections to remote servers with their status and available tools`,execute:()=>Promise.resolve(JSON.stringify(e(),null,2)),name:`soma_connections`}),D=e=>({annotations:{readOnlyHint:!0},description:`Returns health and status information for this server including uptime, sessions, and gateway status`,execute:()=>Promise.resolve(JSON.stringify(e(),null,2)),name:`soma_health`}),O=e=>({flush:()=>Promise.resolve(),recordEvent:t=>{let n={durationMs:t.durationMs,eventName:t.name,timestamp:new Date(t.timestamp).toISOString(),type:t.type,...t.sessionId&&{sessionId:t.sessionId},...t.requestId&&{requestId:t.requestId},...t.errorCategory&&{errorCategory:t.errorCategory},...t.data};t.error?e.withError(Error(t.error)).error(t.type,n):e.info(t.type,n)}}),k={flush:()=>Promise.resolve(),recordEvent:()=>{}},A=(e,t)=>!t||t.length===0?e:Object.fromEntries(Object.entries(e).map(([e,n])=>[e,t.includes(e)?`[REDACTED]`:n])),j=(e,t=1e4)=>{let n=typeof e==`string`?e:JSON.stringify(e);return n&&n.length>t?`${n.slice(0,t)}...[truncated, ${n.length} total chars]`:e},M=e=>t.fromPromise(e),N=(e,t,n)=>({...e,execute:async(r,i)=>{let a=n?.captureLevel??`full`;if(a===`none`)return e.execute(r,i);let o=Date.now(),{requestId:s,sessionId:c}=i,l=a===`full`?A(r,n?.redactInputFields):void 0;return(await M(e.execute(r,i))).fold(n=>{let r=S(n,{toolName:e.name});return t.recordEvent({data:{name:e.name},durationMs:Date.now()-o,error:r.message,errorCategory:r.errorCategory,errorStack:n.stack,input:l,name:e.name,requestId:s,sessionId:c,timestamp:o,type:`tool.error`}),{content:[{text:JSON.stringify(r,null,2),type:`text`}],isError:!0}},r=>(t.recordEvent({data:{name:e.name},durationMs:Date.now()-o,input:l,name:e.name,output:a===`full`?j(r,n?.maxOutputSize):void 0,requestId:s,sessionId:c,timestamp:o,type:`tool.execute`}),r))}}),P=(e,t)=>({...e,load:async n=>{let r=Date.now();return(await M(e.load(n))).fold(n=>{let i=S(n);throw t.recordEvent({data:{name:e.name,uri:e.uri},durationMs:Date.now()-r,error:i.message,errorCategory:i.errorCategory,errorStack:n.stack,name:e.name,timestamp:r,type:`resource.error`}),n},n=>(t.recordEvent({data:{name:e.name,uri:e.uri},durationMs:Date.now()-r,name:e.name,timestamp:r,type:`resource.load`}),n))}}),F=(e,t)=>({...e,load:async(n,r)=>{let i=Date.now();return(await M(e.load(n,r))).fold(n=>{let r=S(n);throw t.recordEvent({data:{name:e.name},durationMs:Date.now()-i,error:r.message,errorCategory:r.errorCategory,errorStack:n.stack,name:e.name,timestamp:i,type:`prompt.error`}),n},n=>(t.recordEvent({data:{name:e.name},durationMs:Date.now()-i,name:e.name,timestamp:i,type:`prompt.load`}),n))}}),I=t=>{let{artifacts:n,backendOptions:r,enableDashboard:i,enableIntrospection:a,gateways:o,logLayer:s,telemetry:c,...l}=t,u=l.name,d=c??(s?O(s):k),m=_(l,r),h=y(d),g=[],v=[],b=[],x=e(0);if(o)for(let e of o)h.add(e);let S=()=>{let e=x.get(),t=e>0?Date.now()-e:0;return{activeSessions:m.sessions.length,gateways:{connected:h.connectedCount,total:h.totalCount},name:u,startedAt:e,status:m.serverState,uptime:t}},C=()=>({prompts:b,resources:v,tools:g});a!==!1&&(m.addTool(D(()=>S())),m.addTool(T(()=>C())),m.addTool(E(()=>h.getInfoAll())));let A=[...n??[]];i!==!1&&A.push(p(()=>S(),()=>C(),()=>h.getInfoAll())),A.length>0&&f(m.getApp(),A),m.on(`connect`,({session:e})=>{d.recordEvent({data:{sessionId:e.sessionId},name:u,timestamp:Date.now(),type:`session.connect`})}),m.on(`disconnect`,({session:e})=>{d.recordEvent({data:{sessionId:e.sessionId},name:u,timestamp:Date.now(),type:`session.disconnect`})});let j=e=>{let t=N(e,d,`captureConfig`in e?e.captureConfig:void 0);m.addTool(t),g.push({description:e.description,name:e.name})},M=e=>{let t=P(e,d);m.addResource(t),v.push({description:e.description,name:e.name,uri:e.uri})},I=e=>{let t=F(e,d);m.addPrompt(t),b.push({description:e.description,name:e.name})};return{get name(){return u},get serverState(){return m.serverState},get sessions(){return m.sessions},addPrompt:I,addPrompts:e=>{for(let t of e)I(t)},addResource:M,addResources:e=>{for(let t of e)M(t)},addResourceTemplate:(...e)=>{m.addResourceTemplate(...e)},addTool:j,addTools:e=>{for(let t of e)j(t)},getApp:()=>m.getApp(),getCapabilities:C,getGatewayManager:()=>h,getHealth:S,removePrompt:e=>{m.removePrompt(e)},removeResource:e=>{m.removeResource(e)},removeTool:e=>{m.removeTool(e)},async start(e){x.set(Date.now()),d.recordEvent({name:u,timestamp:x.get(),type:`server.start`}),await m.start(e),await h.connectAll();for(let e of h.getAll())if(e.status===`connected`&&e.config.proxyTools!==!1){let t=w(e,d);for(let e of t)m.addTool(e)}},async stop(){await h.disconnectAll(),await m.stop(),d.recordEvent({name:u,timestamp:Date.now(),type:`server.stop`}),d.flush&&await d.flush()}}};var L=class extends Error{constructor(e){super(e),this.name=`UserError`}};const R={".avif":`image/avif`,".bmp":`image/bmp`,".gif":`image/gif`,".ico":`image/x-icon`,".jpeg":`image/jpeg`,".jpg":`image/jpeg`,".png":`image/png`,".svg":`image/svg+xml`,".tiff":`image/tiff`,".webp":`image/webp`},z={".aac":`audio/aac`,".flac":`audio/flac`,".m4a":`audio/mp4`,".mp3":`audio/mpeg`,".ogg":`audio/ogg`,".opus":`audio/opus`,".wav":`audio/wav`,".weba":`audio/webm`},B=(e,t,n)=>t[u(new URL(e,`file:///`).pathname).toLowerCase()]??n,V=async(e,t)=>{if(`url`in e){let n=await fetch(e.url);if(!n.ok)throw Error(`Failed to fetch ${t} from URL (${e.url}): ${n.status} ${n.statusText}`);return{data:Buffer.from(await n.arrayBuffer()),source:e.url}}return`path`in e?{data:await c(e.path),source:e.path}:{data:e.buffer}},H=async e=>{let{data:t,source:n}=await V(e,`image`),r=n?B(n,R,`image/png`):`image/png`;return{data:t.toString(`base64`),mimeType:r,type:`image`}},U=async e=>{let{data:t,source:n}=await V(e,`audio`),r=n?B(n,z,`audio/mpeg`):`audio/mpeg`;return{data:t.toString(`base64`),mimeType:r,type:`audio`}},W=e=>({flush:async()=>{await Promise.all(e.map(e=>e.flush?e.flush():Promise.resolve()))},recordEvent:t=>{e.forEach(e=>e.recordEvent(t))}}),G=(e=`[soma]`)=>O(d({prefix:e})),K=t=>{let n=e([]),r=e(void 0),i=e(!1),a=async()=>{let e=n.getAndSet([]);if(e.length===0)return;i.get()||(await s(l(t.filePath),{recursive:!0}),i.set(!0));let r=`${e.map(e=>JSON.stringify(e)).join(`
+`)}\n`;await o(t.filePath,r)},c=()=>{r.get()||r.set(setTimeout(()=>{r.set(void 0),a()},t.flushIntervalMs??1e3))};return{flush:async()=>{let e=r.get();e&&(clearTimeout(e),r.set(void 0)),await a()},recordEvent:e=>{n.update(t=>[...t,e]),c()}}},q=e=>d({prefix:`[${e}]`}).withContext({cell:e});export{k as NoopTelemetry,L as UserError,U as audioContent,b as classifyError,T as createCapabilitiesTool,W as createCompositeTelemetry,E as createConnectionsTool,G as createConsoleTelemetry,p as createDashboardArtifact,q as createDefaultLogger,S as createEnrichedError,_ as createFastMCPBackend,v as createGateway,y as createGatewayManager,D as createHealthTool,K as createJsonFileTelemetry,O as createLogLayerTelemetry,w as createProxiedTools,I as createServer,H as imageContent,f as registerArtifacts,F as wrapPrompt,P as wrapResource,N as wrapTool};

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "somamcp",
+  "version": "1.0.0",
+  "description": "Framework for building MCP servers with telemetry, introspection, and backend abstraction",
+  "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"
+    },
+    "./backend": {
+      "types": "./dist/backend/index.d.ts",
+      "import": "./dist/backend/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "MCP",
+    "server",
+    "telemetry",
+    "introspection",
+    "backend-adapter"
+  ],
+  "author": "Jordan Burke",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "fastmcp": "^3.35.0",
+    "functype": "^0.56.0",
+    "functype-log": "^0.2.0",
+    "hono": "^4.12.12",
+    "zod": "^4.3.6"
+  },
+  "prettier": "ts-builds/prettier",
+  "devDependencies": {
+    "@types/node": "^24.12.2",
+    "get-port-please": "^3.2.0",
+    "ts-builds": "^2.6.4",
+    "tsdown": "^0.21.7"
+  },
+  "scripts": {
+    "validate": "ts-builds validate",
+    "format": "ts-builds format",
+    "format:check": "ts-builds format:check",
+    "lint": "ts-builds lint",
+    "lint:check": "ts-builds lint:check",
+    "typecheck": "ts-builds typecheck",
+    "test": "ts-builds test",
+    "test:watch": "ts-builds test:watch",
+    "test:coverage": "ts-builds test:coverage",
+    "build": "ts-builds build",
+    "dev": "ts-builds dev",
+    "clean": "rimraf dist"
+  }
+}