@lucern/mcp 0.2.0-alpha.1 → 0.2.0-alpha.3

package/dist/index.d.ts

@@ -0,0 +1,307 @@
+import { McpToolContract, GatewayClientConfig, MCP_TOOL_CONTRACTS } from '@lucern/sdk';
+import { IncomingMessage, ServerResponse } from 'node:http';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { ConvexHttpClient } from 'convex/browser';
+
+type ObservationKind = "claim" | "evidence" | "question" | "contradiction" | "judgment" | "note";
+type ObservationRecord = {
+    observationId: string;
+    topicId: string;
+    observationType: ObservationKind;
+    summary: string;
+    source?: string;
+    confidence?: number;
+    tags?: string[];
+    metadata?: Record<string, unknown>;
+    createdAt: number;
+};
+type ObservationContext = {
+    topicId: string;
+    totalObservations: number;
+    latest: ObservationRecord[];
+    semanticMatches: ObservationRecord[];
+    byType: Record<ObservationKind, number>;
+    generatedAt: number;
+};
+type ObservationIngestInput = {
+    topicId: string;
+    observationType: ObservationKind;
+    summary: string;
+    source?: string;
+    confidence?: number;
+    tags?: string[];
+    metadata?: Record<string, unknown>;
+};
+type ObservationContextInput = {
+    topicId: string;
+    query?: string;
+    limit?: number;
+};
+declare class McpObservationStore {
+    private readonly byTopic;
+    ingest(input: ObservationIngestInput): ObservationRecord;
+    list(topicId: string, limit?: number): ObservationRecord[];
+    search(topicId: string, query: string, limit?: number): ObservationRecord[];
+    getContext(input: ObservationContextInput): ObservationContext;
+}
+
+type McpTextContent = {
+    type: "text";
+    text: string;
+};
+type McpToolResult = {
+    content: McpTextContent[];
+    isError?: boolean;
+};
+type McpToolHandler = (params: Record<string, unknown>, contract: McpToolContract) => Promise<McpToolResult>;
+type McpHandlerContext = {
+    sdkConfig: GatewayClientConfig;
+    observationStore?: McpObservationStore;
+    onObservationIngested?: (topicId: string) => Promise<void> | void;
+};
+
+type ToolExecutionTransportKind = "stdio" | "hosted" | "remote" | "chat" | (string & {});
+type ToolExecutionAuthMode = "interactive_user" | "service_principal" | "tenant_api_key" | "session_token" | "unknown";
+type ToolExecutionEnvelope = {
+    toolName: string;
+    params: Record<string, unknown>;
+    contract: McpToolContract;
+    transport: {
+        kind: ToolExecutionTransportKind;
+        surface: "mcp" | "chat";
+        normalizedAt: "handler_boundary";
+    };
+    auth: {
+        mode: ToolExecutionAuthMode;
+    };
+    policy: {
+        requiredScopes: readonly string[];
+        enforcement: "gateway";
+    };
+    audit: {
+        source: "gateway_envelope";
+        structuralFields: readonly [
+            "toolName",
+            "code",
+            "status",
+            "correlationId",
+            "policyTraceId",
+            "invariant"
+        ];
+    };
+};
+type ToolExecutionAuditEvent = {
+    toolName: string;
+    contractName: string;
+    transportKind: ToolExecutionTransportKind;
+    authMode: ToolExecutionAuthMode;
+    requiredScopes: readonly string[];
+    source: "gateway_envelope";
+    isError: boolean;
+    code?: string;
+    status?: number;
+    correlationId?: string | null;
+    policyTraceId?: string | null;
+    invariant?: string | null;
+};
+type ToolExecutionHookSet = {
+    onEnvelope?: (envelope: ToolExecutionEnvelope) => Promise<void> | void;
+    onAuditEvent?: (event: ToolExecutionAuditEvent) => Promise<void> | void;
+};
+type TransportParityDriftKind = "missing_tool" | "degraded_behavior" | "audit_drift" | "policy_drift";
+declare function classifyTransportParityDrift(kind: TransportParityDriftKind): "critical" | "high" | "medium";
+declare function createToolExecutionEnvelope(args: {
+    toolName: string;
+    params: Record<string, unknown>;
+    contract: McpToolContract;
+    transportKind: ToolExecutionTransportKind;
+    authMode: ToolExecutionAuthMode;
+    requiredScopes: readonly string[];
+}): ToolExecutionEnvelope;
+declare function parseToolExecutionMetadata(result: McpToolResult): {
+    isError: boolean;
+    code?: string;
+    status?: number;
+    correlationId?: string | null;
+    policyTraceId?: string | null;
+    invariant?: string | null;
+};
+declare function executeToolWithEnvelope(args: {
+    envelope: ToolExecutionEnvelope;
+    execute: () => Promise<McpToolResult>;
+    hooks?: ToolExecutionHookSet;
+}): Promise<McpToolResult>;
+
+declare const LUCERN_OBSERVER_PROMPT_NAME = "lucern-observer";
+declare const LUCERN_AGENT_MD = "# Lucern \u2014 Reasoning Intelligence\n\nYou are connected to a Lucern reasoning graph. Lucern tracks beliefs, evidence,\nquestions, judgments, and contradictions as structured reasoning state.\n\n## Behavioral Mode\n\nOperate in active observation mode:\n\n1. Watch for claims, evidence, questions, and contradictions.\n2. Suggest graph updates when reasoning-relevant events appear.\n3. Always request user confirmation before mutating graph state.\n4. Preserve uncertainty explicitly; unresolved contradictions are valid.\n\nUse this suggestion format:\n\n`\uD83D\uDD0D Lucern detected: [what changed] -> Want me to log this?`\n\n## Tool Use Defaults\n\n1. Read context first for substantive questions.\n2. Prefer atomic writes: create belief/evidence/question separately, then link edges.\n3. Use worktree lifecycle for investigations: add_worktree -> merge -> push.\n4. Never auto-score confidence without explicit rationale.\n\n## Safety Defaults\n\n1. Do not fabricate evidence.\n2. Do not collapse contradictions automatically.\n3. Keep provenance and rationale in every write path.\n";
+declare function buildLucernObserverPrompt(topicId?: string): string;
+
+declare function runLucernMcpCli(argv?: readonly string[]): Promise<void>;
+
+type ResourceUri = (typeof LUCERN_MCP_RESOURCE_URIS)[number];
+type BuiltinToolName = keyof typeof MCP_TOOL_CONTRACTS;
+type ToolName = string;
+type McpToolExecutor = (toolName: ToolName, params: Record<string, unknown>, contract: McpToolContract) => Promise<unknown>;
+type McpServerRuntime = {
+    registerResource?: (uri: string, handler: (params: Record<string, unknown>) => Promise<unknown>) => void;
+    registerTool?: (name: string, handler: (params: Record<string, unknown>) => Promise<unknown>) => void;
+};
+type McpResourceDescriptor = {
+    uri: ResourceUri;
+    requiredScopes: readonly string[];
+};
+type McpToolDescriptor = {
+    name: ToolName;
+    requiredScopes: readonly string[];
+    contract: McpToolContract;
+    implemented: boolean;
+    source: "platform" | "custom";
+};
+type AdditionalMcpTool = {
+    name: ToolName;
+    requiredScopes: readonly string[];
+    contract: McpToolContract;
+    handler: McpToolHandler;
+    implemented?: boolean;
+    source?: "platform" | "custom";
+};
+declare const LUCERN_MCP_RESOURCE_URIS: readonly ["lucern://schema/kernel", "lucern://schema/packs/{packId}", "lucern://schema/extensions", "lucern://graph/sample", "lucern://api/openapi", "lucern://sdk/examples", "lucern://docs/invariants"];
+declare const LUCERN_MCP_TOOL_NAMES: BuiltinToolName[];
+declare function createLucernMcpServer(options?: {
+    apiKey?: string;
+    sessionToken?: string;
+    baseUrl?: string;
+    fetchImpl?: typeof fetch;
+    toolExecutor?: McpToolExecutor;
+    observationStore?: McpObservationStore;
+    onObservationIngested?: (topicId: string) => Promise<void> | void;
+    transportKind?: ToolExecutionTransportKind;
+    authMode?: ToolExecutionAuthMode;
+    onEnvelope?: (envelope: ToolExecutionEnvelope) => Promise<void> | void;
+    onAuditEvent?: (event: ToolExecutionAuditEvent) => Promise<void> | void;
+    additionalTools?: readonly AdditionalMcpTool[];
+}): {
+    server: McpServerRuntime;
+    resources: readonly McpResourceDescriptor[];
+    tools: readonly McpToolDescriptor[];
+    authErrorCodes: readonly string[];
+    rateLimitSignals: readonly string[];
+    handlers: Record<string, McpToolHandler>;
+    implementedToolNames: ToolName[];
+    unimplementedToolNames: ToolName[];
+};
+
+type StandaloneRuntime = ReturnType<typeof createLucernMcpServer>;
+type StandaloneMcpServerOptions = {
+    apiKey?: string;
+    sessionToken?: string;
+    baseUrl?: string;
+    fetchImpl?: typeof fetch;
+    transportKind?: ToolExecutionTransportKind;
+    authMode?: ToolExecutionAuthMode;
+    onEnvelope?: (envelope: ToolExecutionEnvelope) => Promise<void> | void;
+    onAuditEvent?: (event: ToolExecutionAuditEvent) => Promise<void> | void;
+    additionalTools?: readonly AdditionalMcpTool[];
+};
+declare function createLucernStandaloneMcpServer(options?: StandaloneMcpServerOptions): {
+    server: McpServer;
+    runtime: StandaloneRuntime;
+    resourceUris: string[];
+    promptNames: string[];
+};
+declare function startLucernMcpStdioServer(options?: StandaloneMcpServerOptions): Promise<{
+    server: McpServer;
+    runtime: StandaloneRuntime;
+    resourceUris: string[];
+    promptNames: string[];
+}>;
+
+type RemoteMcpServerOptions = StandaloneMcpServerOptions & {
+    host?: string;
+    port?: number;
+    path?: string;
+    healthPath?: string;
+    serverAuthToken?: string;
+    allowApiKeyPassthrough?: boolean;
+};
+declare function createLucernMcpHttpRequestHandler(options?: RemoteMcpServerOptions): (req: IncomingMessage, res: ServerResponse) => Promise<void>;
+declare function startLucernMcpHttpServer(options?: RemoteMcpServerOptions): Promise<{
+    host: string;
+    port: number;
+    path: string;
+    healthPath: string;
+    close: () => Promise<void>;
+}>;
+
+declare function createMcpHandlerRegistry(context: McpHandlerContext): Record<string, McpToolHandler>;
+
+declare function resolveCredentials(): {
+    lucernResolved: boolean;
+    stackResolved: boolean;
+    mcResolved: boolean;
+    source: string;
+    rawLucernApiKey?: string;
+    rawStackApiKey?: string;
+    rawUserToken?: string;
+};
+
+type LegacyAuthContext = {
+    sessionType: "agent" | "user";
+    userId: string;
+    tenantId: string;
+    role: string;
+    allowedTopics: string[] | null;
+    groupIds: string[];
+    permittedPackKeys: string[];
+    sessionId: string;
+    principalId?: string;
+    principalType?: string;
+    workspaceId?: string;
+    scopes?: string[];
+    authMode?: string;
+    roles?: string[];
+    transportKind?: string;
+    useSdk?: boolean;
+    gatewayBaseUrl?: string;
+    getAuthHeaders?: () => Promise<Record<string, string>>;
+    lucernClient?: {
+        context: {
+            discover(input: {
+                query: string;
+                topK?: number;
+                includeNeighborhood?: boolean;
+            }): Promise<unknown>;
+        };
+    };
+};
+
+declare function loadLegacyDiscoveryHandlers(): Promise<{
+    discover(args: Record<string, unknown>, ctx: LegacyAuthContext): Promise<Record<string, unknown>>;
+}>;
+
+type LegacyAuthenticatedHandler = (args: Record<string, unknown>, ctx: LegacyAuthContext) => Promise<Record<string, unknown>>;
+declare function buildLegacyAuthenticatedHandlerMap(): Promise<Record<string, LegacyAuthenticatedHandler>>;
+
+declare const BOOTSTRAP_MCP_TOOLS: Record<string, McpToolContract>;
+declare const COORDINATION_MCP_TOOLS: Record<string, McpToolContract>;
+declare const EPISTEMIC_CONTRACT_MCP_TOOLS: Record<string, McpToolContract>;
+declare const SCOPE_MCP_TOOLS: Record<string, McpToolContract>;
+
+type JsonRecord = Record<string, unknown>;
+declare function initializeLucernScriptEnv(): void;
+declare function readArg(name: string, fallback?: string): string | undefined;
+declare function createLucernMcpClient(): Promise<Client>;
+declare function createLucernAdminClient(): ConvexHttpClient;
+declare function resolveMcpSessionTenantId(): Promise<string | undefined>;
+declare function callMcpTool<T extends JsonRecord = JsonRecord>(client: Client, toolName: string, args: JsonRecord): Promise<T>;
+declare function closeMcpClient(client: Client): Promise<void>;
+
+type ContextRankingProfile = "baseline_v1" | "hybrid_v1" | "weighted_v1";
+type ValidationResult = {
+    valid: boolean;
+    errors: string[];
+};
+declare function validateContextPackSchema(payload: unknown): ValidationResult;
+
+export { BOOTSTRAP_MCP_TOOLS, COORDINATION_MCP_TOOLS, type ContextRankingProfile, EPISTEMIC_CONTRACT_MCP_TOOLS, type JsonRecord, LUCERN_AGENT_MD, LUCERN_MCP_RESOURCE_URIS, LUCERN_MCP_TOOL_NAMES, LUCERN_OBSERVER_PROMPT_NAME, type LegacyAuthContext, type LegacyAuthenticatedHandler, McpObservationStore, type RemoteMcpServerOptions, SCOPE_MCP_TOOLS, type StandaloneMcpServerOptions, type ToolExecutionAuditEvent, type ToolExecutionAuthMode, type ToolExecutionEnvelope, type ToolExecutionTransportKind, type TransportParityDriftKind, buildLegacyAuthenticatedHandlerMap, buildLucernObserverPrompt, callMcpTool, classifyTransportParityDrift, closeMcpClient, createLucernAdminClient, createLucernMcpClient, createLucernMcpHttpRequestHandler, createLucernMcpServer, createLucernStandaloneMcpServer, createMcpHandlerRegistry, createToolExecutionEnvelope, executeToolWithEnvelope, initializeLucernScriptEnv, loadLegacyDiscoveryHandlers, parseToolExecutionMetadata, readArg, resolveCredentials as resolveLegacyMcpCredentials, resolveMcpSessionTenantId, runLucernMcpCli, startLucernMcpHttpServer, startLucernMcpStdioServer, validateContextPackSchema };