@usekova/mcp-server 0.1.0 → 2.0.0

package/README.md

@@ -0,0 +1,57 @@
+# @usekova/mcp-server
+
+Model Context Protocol (MCP) server that exposes Stele covenant operations as tools to any AI agent via JSON-RPC 2.0.
+
+## Installation
+
+```bash
+npm install @usekova/mcp-server
+```
+
+## Key APIs
+
+- **SteleServer**: MCP server class that handles JSON-RPC 2.0 messages and exposes Stele tools. Supports `initialize`, `tools/list`, `tools/call`, and `ping` methods.
+- **createAuthMiddleware()**: Authentication middleware for securing MCP endpoints.
+- **JSON_RPC_ERRORS**: Standard JSON-RPC 2.0 error code constants.
+
+### Exposed Tools
+
+| Tool | Description |
+|------|-------------|
+| `create_covenant` | Create a signed covenant document with CCL constraints |
+| `verify_covenant` | Verify a covenant document (signature, expiry, CCL syntax) |
+| `evaluate_action` | Check if an action on a resource is permitted by a covenant |
+| `create_identity` | Create an agent identity with model attestation and capabilities |
+| `parse_ccl` | Parse CCL source text into a structured document |
+| `list_covenants` | List stored covenants with optional issuer/beneficiary filters |
+
+## Usage
+
+```typescript
+import { SteleServer } from '@usekova/mcp-server';
+import { MemoryStore } from '@usekova/store';
+
+const server = new SteleServer(new MemoryStore(), {
+  name: 'my-stele-server',
+  version: '1.0.0',
+});
+
+// Handle a JSON-RPC message
+const response = await server.handleMessage({
+  jsonrpc: '2.0',
+  id: 1,
+  method: 'tools/list',
+  params: {},
+});
+
+// Call a tool directly
+const result = await server.callTool('evaluate_action', {
+  covenantId: 'abc123',
+  action: 'read',
+  resource: '/data',
+});
+```
+
+## Docs
+
+See the [Stele SDK root documentation](../../README.md) for the full API reference.

package/dist/auth.d.ts

@@ -0,0 +1,51 @@
+/**
+ * MCP Server authentication middleware.
+ *
+ * Provides API key authentication, Ed25519 signature-based authentication,
+ * per-client rate limiting, and key revocation for the MCP server.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Options for configuring the authentication middleware.
+ */
+export interface MCPAuthOptions {
+    /** List of valid API keys for API key authentication. */
+    apiKeys?: string[];
+    /** Hex-encoded Ed25519 public keys trusted for signature-based authentication. */
+    trustedKeys?: string[];
+    /** Maximum number of requests per client per minute. */
+    rateLimitPerMinute?: number;
+}
+/**
+ * Represents an authenticated client request.
+ */
+export interface AuthenticatedRequest {
+    /** Unique identifier for the client. */
+    clientId: string;
+    /** The authentication method used. */
+    authMethod: 'api-key' | 'signature' | 'none';
+    /** ISO 8601 timestamp when the authentication was performed. */
+    timestamp: string;
+}
+/**
+ * Create an authentication middleware for the MCP server.
+ *
+ * Supports three authentication modes:
+ * 1. **API key**: Client provides an `x-api-key` header.
+ * 2. **Signature**: Client provides `x-public-key`, `x-signature`, and
+ *    `x-signature-payload` headers. The payload is verified against the
+ *    trusted public keys.
+ * 3. **None**: If no authentication options are configured, all requests
+ *    are allowed without authentication.
+ *
+ * @param options - Authentication configuration options.
+ * @returns An object with `authenticate`, `isRateLimited`, `revokeKey`, and `listClients` methods.
+ */
+export declare function createAuthMiddleware(options: MCPAuthOptions): {
+    authenticate(headers: Record<string, string>): AuthenticatedRequest;
+    isRateLimited(clientId: string): boolean;
+    revokeKey(key: string): void;
+    listClients(): string[];
+};
+//# sourceMappingURL=auth.d.ts.map

package/dist/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AASH;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,yDAAyD;IACzD,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,kFAAkF;IAClF,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,wDAAwD;IACxD,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,wCAAwC;IACxC,QAAQ,EAAE,MAAM,CAAC;IACjB,sCAAsC;IACtC,UAAU,EAAE,SAAS,GAAG,WAAW,GAAG,MAAM,CAAC;IAC7C,gEAAgE;IAChE,SAAS,EAAE,MAAM,CAAC;CACnB;AAUD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,cAAc,GAAG;IAC7D,YAAY,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,oBAAoB,CAAC;IACpE,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;IACzC,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,WAAW,IAAI,MAAM,EAAE,CAAC;CACzB,CAoJA"}

package/dist/auth.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=auth.test.d.ts.map

package/dist/auth.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.test.d.ts","sourceRoot":"","sources":["../src/auth.test.ts"],"names":[],"mappings":""}

package/dist/bin.d.ts

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+/**
+ * Stele MCP Server — stdio transport.
+ *
+ * Reads newline-delimited JSON-RPC 2.0 messages from stdin,
+ * dispatches them to the SteleServer, and writes responses to stdout.
+ *
+ * Usage:
+ *   npx stele-mcp
+ *   echo '{"jsonrpc":"2.0","method":"initialize","id":1}' | npx stele-mcp
+ */
+export {};
+//# sourceMappingURL=bin.d.ts.map

package/dist/bin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.d.ts","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":";AACA;;;;;;;;;GASG"}

package/dist/certification.d.ts

@@ -0,0 +1,112 @@
+/**
+ * MCP Server Certification system.
+ *
+ * Proactively certifies MCP servers with trust reports and a badge system.
+ * Evaluates servers against a set of criteria and assigns a badge level
+ * (none, bronze, silver, gold, platinum) based on the resulting score.
+ *
+ * @packageDocumentation
+ */
+/** Badge levels awarded to MCP servers based on certification score. */
+export type BadgeLevel = 'none' | 'bronze' | 'silver' | 'gold' | 'platinum';
+/** Profile describing an MCP server's identity and capabilities. */
+export interface MCPServerProfile {
+    /** Unique identifier for the server. */
+    serverId: string;
+    /** Human-readable server name. */
+    serverName: string;
+    /** Server version string. */
+    version: string;
+    /** List of capabilities the server supports. */
+    capabilities: string[];
+    /** Timestamp when the server was first registered (ms since epoch). */
+    registeredAt: number;
+    /** Timestamp when the server was last audited (ms since epoch). */
+    lastAuditedAt: number;
+}
+/** Criteria used to evaluate an MCP server for certification. */
+export interface CertificationCriteria {
+    /** Whether the server has a covenant defined. */
+    covenantDefined: boolean;
+    /** Whether the server's identity has been verified. */
+    identityVerified: boolean;
+    /** Whether attestation is enabled. */
+    attestationEnabled: boolean;
+    /** The enforcement mode in use. */
+    enforcementMode: 'enforce' | 'audit' | 'none';
+    /** Server uptime percentage (0-100). */
+    uptimePercentage: number;
+    /** 95th-percentile response time in milliseconds. */
+    responseTimeP95Ms: number;
+    /** Whether the server has passed a security audit. */
+    securityAuditPassed: boolean;
+    /** Whether documentation is complete. */
+    documentationComplete: boolean;
+}
+/** The result of evaluating an MCP server against certification criteria. */
+export interface ServerCertification {
+    /** The server profile. */
+    profile: MCPServerProfile;
+    /** The criteria used for evaluation. */
+    criteria: CertificationCriteria;
+    /** The badge level awarded. */
+    badge: BadgeLevel;
+    /** The numeric score (0-100). */
+    score: number;
+    /** Human-readable trust report. */
+    report: string;
+    /** Timestamp when the certification was issued (ms since epoch). */
+    certifiedAt: number;
+    /** Timestamp when the certification expires (ms since epoch). */
+    expiresAt: number;
+}
+/**
+ * Create a new MCP server profile.
+ *
+ * @param params - Profile parameters.
+ * @returns A complete MCPServerProfile with timestamps set to now.
+ */
+export declare function createServerProfile(params: {
+    serverId: string;
+    serverName: string;
+    version: string;
+    capabilities: string[];
+}): MCPServerProfile;
+/**
+ * Evaluate an MCP server against certification criteria and produce
+ * a full ServerCertification including badge, score, and report.
+ *
+ * @param profile - The server profile to evaluate.
+ * @param criteria - The certification criteria.
+ * @returns A complete ServerCertification.
+ */
+export declare function evaluateServer(profile: MCPServerProfile, criteria: CertificationCriteria): ServerCertification;
+/**
+ * Generate an aggregate trust report across multiple server certifications.
+ *
+ * @param certifications - Array of server certifications to analyze.
+ * @returns An aggregate trust report with distributions and recommendations.
+ */
+export declare function generateTrustReport(certifications: ServerCertification[]): {
+    totalServers: number;
+    certifiedServers: number;
+    averageScore: number;
+    badgeDistribution: Record<BadgeLevel, number>;
+    topServers: Array<{
+        serverId: string;
+        score: number;
+        badge: BadgeLevel;
+    }>;
+    recommendations: string[];
+};
+/**
+ * Renew a server certification with updated criteria.
+ *
+ * Re-evaluates the server with the new criteria and updates timestamps.
+ *
+ * @param cert - The existing certification to renew.
+ * @param newCriteria - The updated certification criteria.
+ * @returns A new ServerCertification with fresh timestamps and score.
+ */
+export declare function renewCertification(cert: ServerCertification, newCriteria: CertificationCriteria): ServerCertification;
+//# sourceMappingURL=certification.d.ts.map

package/dist/certification.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"certification.d.ts","sourceRoot":"","sources":["../src/certification.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,wEAAwE;AACxE,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,QAAQ,GAAG,QAAQ,GAAG,MAAM,GAAG,UAAU,CAAC;AAE5E,oEAAoE;AACpE,MAAM,WAAW,gBAAgB;IAC/B,wCAAwC;IACxC,QAAQ,EAAE,MAAM,CAAC;IACjB,kCAAkC;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,6BAA6B;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,gDAAgD;IAChD,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,uEAAuE;IACvE,YAAY,EAAE,MAAM,CAAC;IACrB,mEAAmE;IACnE,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,iEAAiE;AACjE,MAAM,WAAW,qBAAqB;IACpC,iDAAiD;IACjD,eAAe,EAAE,OAAO,CAAC;IACzB,uDAAuD;IACvD,gBAAgB,EAAE,OAAO,CAAC;IAC1B,sCAAsC;IACtC,kBAAkB,EAAE,OAAO,CAAC;IAC5B,mCAAmC;IACnC,eAAe,EAAE,SAAS,GAAG,OAAO,GAAG,MAAM,CAAC;IAC9C,wCAAwC;IACxC,gBAAgB,EAAE,MAAM,CAAC;IACzB,qDAAqD;IACrD,iBAAiB,EAAE,MAAM,CAAC;IAC1B,sDAAsD;IACtD,mBAAmB,EAAE,OAAO,CAAC;IAC7B,yCAAyC;IACzC,qBAAqB,EAAE,OAAO,CAAC;CAChC;AAED,6EAA6E;AAC7E,MAAM,WAAW,mBAAmB;IAClC,0BAA0B;IAC1B,OAAO,EAAE,gBAAgB,CAAC;IAC1B,wCAAwC;IACxC,QAAQ,EAAE,qBAAqB,CAAC;IAChC,+BAA+B;IAC/B,KAAK,EAAE,UAAU,CAAC;IAClB,iCAAiC;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,mCAAmC;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,oEAAoE;IACpE,WAAW,EAAE,MAAM,CAAC;IACpB,iEAAiE;IACjE,SAAS,EAAE,MAAM,CAAC;CACnB;AAkBD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE;IAC1C,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB,GAAG,gBAAgB,CAUnB;AAkGD;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,gBAAgB,EACzB,QAAQ,EAAE,qBAAqB,GAC9B,mBAAmB,CAerB;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,cAAc,EAAE,mBAAmB,EAAE,GAAG;IAC1E,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB,EAAE,MAAM,CAAC;IACzB,YAAY,EAAE,MAAM,CAAC;IACrB,iBAAiB,EAAE,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;IAC9C,UAAU,EAAE,KAAK,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,UAAU,CAAA;KAAE,CAAC,CAAC;IAC1E,eAAe,EAAE,MAAM,EAAE,CAAC;CAC3B,CAiFA;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,mBAAmB,EACzB,WAAW,EAAE,qBAAqB,GACjC,mBAAmB,CAOrB"}

package/dist/certification.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=certification.test.d.ts.map

package/dist/certification.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"certification.test.d.ts","sourceRoot":"","sources":["../src/certification.test.ts"],"names":[],"mappings":""}

package/dist/index.d.ts

@@ -1,8 +1,68 @@
 /**
- * @stele/mcp-server — Model Context Protocol server that exposes
+ * @usekova/mcp-server -- Model Context Protocol server that exposes
  * Stele tools to any AI agent.
  *
+ * Implements JSON-RPC 2.0 over stdio, with tool definitions that map
+ * to @usekova/sdk, @usekova/store, and @usekova/crypto operations.
+ *
  * @packageDocumentation
  */
-export {};
+import { MemoryStore } from '@usekova/store';
+import type { JsonRpcRequest, JsonRpcResponse, ToolDefinition, ToolResult, MCPServerOptions } from './types';
+export type { JsonRpcRequest, JsonRpcResponse, JsonRpcSuccessResponse, JsonRpcErrorResponse, JsonRpcErrorDetail, ToolDefinition, ToolResult, ToolResultContent, ToolInputSchema, MCPServerOptions, } from './types';
+export { JSON_RPC_ERRORS } from './types';
+export { createAuthMiddleware } from './auth';
+export type { MCPAuthOptions, AuthenticatedRequest } from './auth';
+/**
+ * MCP server that exposes Stele protocol operations as tools via JSON-RPC 2.0.
+ *
+ * Accepts a {@link MemoryStore} for persisting covenant documents and provides
+ * methods for handling MCP protocol messages, listing tools, and calling tools.
+ */
+export declare class SteleServer {
+    /** The backing store for covenant documents. */
+    readonly store: MemoryStore;
+    /** The SDK client used for operations. */
+    private readonly client;
+    /** Server name. */
+    readonly name: string;
+    /** Server version. */
+    readonly version: string;
+    constructor(store: MemoryStore, options?: MCPServerOptions);
+    /**
+     * Return all available tool definitions with their JSON Schema input schemas.
+     */
+    listTools(): ToolDefinition[];
+    /**
+     * Call a named tool with the given arguments.
+     *
+     * @param name - The tool name (must match one of the tool definitions).
+     * @param args - The tool arguments matching the tool's input schema.
+     * @returns A {@link ToolResult} containing the output or error.
+     */
+    callTool(name: string, args: Record<string, unknown>): Promise<ToolResult>;
+    /**
+     * Handle a JSON-RPC 2.0 message and return the appropriate response.
+     *
+     * Supports the following MCP methods:
+     * - `initialize` -- Returns server info and capabilities
+     * - `tools/list` -- Returns available tool definitions
+     * - `tools/call` -- Executes a tool and returns the result
+     * - `ping` -- Returns a pong
+     *
+     * @param message - A parsed JSON-RPC request object.
+     * @returns A JSON-RPC response object.
+     */
+    handleMessage(message: JsonRpcRequest): Promise<JsonRpcResponse>;
+    private _createCovenant;
+    private _verifyCovenant;
+    private _evaluateAction;
+    private _createIdentity;
+    private _parseCCL;
+    private _listCovenants;
+    private _successResponse;
+    private _errorResponse;
+    private _toolSuccess;
+    private _toolError;
+}
 //# 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;;;;;GAKG;AAEH,OAAO,EAAE,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAI7C,OAAO,KAAK,EACV,cAAc,EACd,eAAe,EAIf,cAAc,EACd,UAAU,EAGV,gBAAgB,EACjB,MAAM,SAAS,CAAC;AAOjB,YAAY,EACV,cAAc,EACd,eAAe,EACf,sBAAsB,EACtB,oBAAoB,EACpB,kBAAkB,EAClB,cAAc,EACd,UAAU,EACV,iBAAiB,EACjB,eAAe,EACf,gBAAgB,GACjB,MAAM,SAAS,CAAC;AAEjB,OAAO,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE1C,OAAO,EAAE,oBAAoB,EAAE,MAAM,QAAQ,CAAC;AAC9C,YAAY,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,QAAQ,CAAC;AAmKnE;;;;;GAKG;AACH,qBAAa,WAAW;IACtB,gDAAgD;IAChD,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAE5B,0CAA0C;IAC1C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAa;IAEpC,mBAAmB;IACnB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,sBAAsB;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;gBAEb,KAAK,EAAE,WAAW,EAAE,OAAO,CAAC,EAAE,gBAAgB;IAS1D;;OAEG;IACH,SAAS,IAAI,cAAc,EAAE;IAM7B;;;;;;OAMG;IACG,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,UAAU,CAAC;IAwBhF;;;;;;;;;;;OAWG;IACG,aAAa,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,eAAe,CAAC;YAuFxD,eAAe;YAwDf,eAAe;YAuBf,eAAe;YAmCf,eAAe;YAwDf,SAAS;YAsCT,cAAc;IA8B5B,OAAO,CAAC,gBAAgB;IAQxB,OAAO,CAAC,cAAc;IAatB,OAAO,CAAC,YAAY;IAMpB,OAAO,CAAC,UAAU;CAMnB"}