apcore-mcp 0.6.1 → 0.7.0

package/README.md

@@ -16,6 +16,7 @@ Converts apcore module registries into [Model Context Protocol (MCP)](https://mo
 - **Annotation Mapping** — Map module annotations to MCP hints and OpenAI description suffixes
 - **Error Mapping** — Sanitize internal errors for safe client-facing responses
 - **Dynamic Registration** — Listen for registry changes and update tools at runtime
+- **Tool Explorer** — Browser-based UI for browsing schemas and testing tools interactively
 - **CLI** — Launch an MCP server from the command line
 
 ## Requirements
@@ -78,6 +79,73 @@ npx apcore-mcp --extensions-dir ./extensions --transport sse --port 8000
 | `--name` | `apcore-mcp` | MCP server name |
 | `--version` | package version | MCP server version |
 | `--log-level` | `INFO` | `DEBUG`, `INFO`, `WARNING`, `ERROR` |
+| `--explorer` | off | Enable the browser-based Tool Explorer UI (HTTP only) |
+| `--explorer-prefix` | `/explorer` | URL prefix for the explorer UI |
+| `--allow-execute` | off | Allow tool execution from the explorer UI |
+| `--jwt-secret` | — | JWT secret key for Bearer token authentication |
+| `--jwt-algorithm` | `HS256` | JWT algorithm |
+| `--jwt-audience` | — | Expected JWT audience claim |
+| `--jwt-issuer` | — | Expected JWT issuer claim |
+| `--jwt-require-auth` | `true` | Require auth (use `--no-jwt-require-auth` for permissive mode) |
+| `--exempt-paths` | `/health,/metrics` | Comma-separated paths exempt from auth |
+
+## MCP Client Configuration
+
+### Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "apcore": {
+      "command": "npx",
+      "args": ["apcore-mcp", "--extensions-dir", "/path/to/your/extensions"]
+    }
+  }
+}
+```
+
+### Claude Code
+
+Add to `.mcp.json` in your project root:
+
+```json
+{
+  "mcpServers": {
+    "apcore": {
+      "command": "npx",
+      "args": ["apcore-mcp", "--extensions-dir", "./extensions"]
+    }
+  }
+}
+```
+
+### Cursor
+
+Add to `.cursor/mcp.json` in your project root:
+
+```json
+{
+  "mcpServers": {
+    "apcore": {
+      "command": "npx",
+      "args": ["apcore-mcp", "--extensions-dir", "./extensions"]
+    }
+  }
+}
+```
+
+### Remote HTTP access
+
+```bash
+npx apcore-mcp --extensions-dir ./extensions \
+    --transport streamable-http \
+    --host 0.0.0.0 \
+    --port 9000
+```
+
+Connect any MCP client to `http://your-host:9000/mcp`.
 
 ## API Reference
 
@@ -94,10 +162,101 @@ function serve(
     port?: number;
     name?: string;
     version?: string;
+    explorer?: boolean;
+    explorerPrefix?: string;
+    allowExecute?: boolean;
+    authenticator?: Authenticator;
+    exemptPaths?: string[];
   }
 ): Promise<void>;
 ```
 
+### Tool Explorer
+
+When `explorer: true` is passed to `serve()`, a browser-based Tool Explorer UI is mounted on HTTP transports. It provides an interactive page for browsing tool schemas and testing tool execution.
+
+```typescript
+await serve(registry, {
+  transport: "streamable-http",
+  explorer: true,
+  allowExecute: true,
+});
+// Open http://127.0.0.1:8000/explorer/ in a browser
+```
+
+**Endpoints:**
+
+| Endpoint | Description |
+|----------|-------------|
+| `GET /explorer/` | Interactive HTML page (self-contained, no external dependencies) |
+| `GET /explorer/tools` | JSON array of all tools with name, description, annotations |
+| `GET /explorer/tools/<name>` | Full tool detail with inputSchema |
+| `POST /explorer/tools/<name>/call` | Execute a tool (requires `allowExecute: true`) |
+
+- **HTTP transports only** (`streamable-http`, `sse`). Silently ignored for `stdio`.
+- **Execution disabled by default** — set `allowExecute: true` to enable Try-it.
+- **Custom prefix** — use `explorerPrefix: "/browse"` to mount at a different path.
+- **Authorization UI** — Swagger-UI-style Authorization input field. Paste a Bearer token to authenticate tool execution requests. Generated cURL commands automatically include the Authorization header.
+
+### JWT Authentication
+
+apcore-mcp supports JWT Bearer token authentication for HTTP-based transports.
+
+#### Programmatic Usage
+
+```typescript
+import { serve, JWTAuthenticator } from "apcore-mcp";
+
+const authenticator = new JWTAuthenticator({
+  secret: "your-secret-key",
+  algorithms: ["HS256"],
+  audience: "my-app",
+  issuer: "auth-service",
+  // Map custom claims to Identity fields
+  claimMapping: {
+    id: "sub",
+    type: "type",
+    roles: "roles",
+    attrs: ["email", "org"],  // Extra claims → Identity.attrs
+  },
+  // Claims that must be present in the token (default: ["sub"])
+  requireClaims: ["sub", "email"],
+  // Set to false for permissive mode (allow unauthenticated requests)
+  requireAuth: true,
+});
+
+await serve(executor, {
+  transport: "streamable-http",
+  authenticator,
+  // Custom exempt paths (default: ["/health", "/metrics"])
+  exemptPaths: ["/health", "/metrics", "/status"],
+});
+```
+
+#### CLI Flags
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--jwt-secret` | — | JWT secret key for Bearer token authentication |
+| `--jwt-algorithm` | `HS256` | JWT algorithm |
+| `--jwt-audience` | — | Expected audience claim |
+| `--jwt-issuer` | — | Expected issuer claim |
+| `--jwt-require-auth` | `true` | Require auth. Use `--no-jwt-require-auth` for permissive mode |
+| `--exempt-paths` | `/health,/metrics` | Comma-separated paths exempt from auth |
+
+#### curl Examples
+
+```bash
+# Authenticated request
+curl -X POST http://localhost:8000/mcp \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer <your-jwt-token>" \
+  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'
+
+# Health check (always exempt)
+curl http://localhost:8000/health
+```
+
 ### `toOpenaiTools(registryOrExecutor, options?)`
 
 Export apcore modules as OpenAI-compatible tool definitions.
@@ -128,16 +287,25 @@ src/
 ├── index.ts              # Public API: serve(), toOpenaiTools()
 ├── cli.ts                # CLI entry point
 ├── types.ts              # TypeScript interfaces
+├── helpers.ts            # reportProgress() / elicit() helpers
 ├── adapters/
 │   ├── schema.ts         # JSON Schema $ref inlining
 │   ├── annotations.ts    # Module annotations -> MCP hints
 │   ├── errors.ts         # Error sanitization
 │   └── idNormalizer.ts   # Dot-notation <-> dash-notation
+├── auth/
+│   ├── jwt.ts            # JWT Bearer token authenticator
+│   ├── storage.ts        # AsyncLocalStorage identity propagation
+│   └── types.ts          # Authenticator / Identity interfaces
 ├── converters/
 │   └── openai.ts         # OpenAI tool definition converter
+├── explorer/
+│   ├── handler.ts        # Explorer HTTP route handler
+│   └── html.ts           # Self-contained HTML/CSS/JS page
 └── server/
     ├── factory.ts        # MCP Server creation & handler registration
     ├── router.ts         # Tool call execution routing
+    ├── context.ts        # BridgeContext for executor call chains
     ├── transport.ts      # Transport lifecycle (stdio/HTTP/SSE)
     └── listener.ts       # Dynamic registry event listener
 ```
@@ -176,18 +344,7 @@ npm run dev
 
 ## Testing
 
-100 tests across 10 test suites with 96%+ line coverage:
-
-| Module | Coverage |
-|---|---|
-| annotations.ts | 100% |
-| idNormalizer.ts | 100% |
-| factory.ts | 100% |
-| router.ts | 100% |
-| errors.ts | 98.8% |
-| schema.ts | 97.0% |
-| openai.ts | 91.7% |
-| listener.ts | 89.7% |
+284 tests across 22 test suites.
 
 ## License
 

package/dist/auth/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Auth module barrel exports.
+ */
+export type { Authenticator, Identity } from "./types.js";
+export { JWTAuthenticator } from "./jwt.js";
+export type { ClaimMapping, JWTAuthenticatorOptions } from "./jwt.js";
+export { identityStorage, getCurrentIdentity } from "./storage.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/auth/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,YAAY,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC1D,OAAO,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAC5C,YAAY,EAAE,YAAY,EAAE,uBAAuB,EAAE,MAAM,UAAU,CAAC;AACtE,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC"}

package/dist/auth/index.js

@@ -0,0 +1,6 @@
+/**
+ * Auth module barrel exports.
+ */
+export { JWTAuthenticator } from "./jwt.js";
+export { identityStorage, getCurrentIdentity } from "./storage.js";
+//# sourceMappingURL=index.js.map

package/dist/auth/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/auth/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAE5C,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC"}

package/dist/auth/jwt.d.ts

@@ -0,0 +1,59 @@
+/**
+ * JWT Authenticator — verifies Bearer tokens and maps claims to Identity.
+ *
+ * Mirrors the Python `JWTAuthenticator` from apcore-mcp-python.
+ */
+import type { IncomingMessage } from "node:http";
+import jwt from "jsonwebtoken";
+import { type Identity } from "apcore-js";
+import type { Authenticator } from "./types.js";
+/** Mapping from JWT claims to Identity fields. */
+export interface ClaimMapping {
+    /** JWT claim for Identity.id. Default: "sub" */
+    id?: string;
+    /** JWT claim for Identity.type. Default: "type" */
+    type?: string;
+    /** JWT claim for Identity.roles. Default: "roles" */
+    roles?: string;
+    /** Extra claims to copy into Identity.attrs. */
+    attrs?: string[];
+}
+/** Options for constructing a JWTAuthenticator. */
+export interface JWTAuthenticatorOptions {
+    /** Secret key (symmetric) or public key (asymmetric) for token verification. */
+    secret: string;
+    /** Allowed algorithms. Default: ["HS256"] */
+    algorithms?: jwt.Algorithm[];
+    /** Expected audience claim. */
+    audience?: string;
+    /** Expected issuer claim. */
+    issuer?: string;
+    /** Custom claim-to-Identity field mapping. */
+    claimMapping?: ClaimMapping;
+    /** Claims that must be present in the token. Default: ["sub"] */
+    requireClaims?: string[];
+    /** If true (default), unauthenticated requests are rejected. If false, they proceed without identity. */
+    requireAuth?: boolean;
+}
+/**
+ * Authenticator that verifies JWT Bearer tokens from the Authorization header.
+ *
+ * Returns an Identity on success, or `null` if:
+ * - No Authorization header is present
+ * - The header is not a valid "Bearer <token>" format
+ * - The token fails verification (expired, wrong signature, etc.)
+ */
+export declare class JWTAuthenticator implements Authenticator {
+    private readonly _secret;
+    private readonly _algorithms;
+    private readonly _audience?;
+    private readonly _issuer?;
+    private readonly _claimMapping;
+    private readonly _requireClaims;
+    private readonly _requireAuth;
+    constructor(options: JWTAuthenticatorOptions);
+    /** Whether unauthenticated requests should be rejected. */
+    get requireAuth(): boolean;
+    authenticate(req: IncomingMessage): Promise<Identity | null>;
+}
+//# sourceMappingURL=jwt.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"jwt.d.ts","sourceRoot":"","sources":["../../src/auth/jwt.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AACjD,OAAO,GAAG,MAAM,cAAc,CAAC;AAC/B,OAAO,EAAkB,KAAK,QAAQ,EAAE,MAAM,WAAW,CAAC;AAC1D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,kDAAkD;AAClD,MAAM,WAAW,YAAY;IAC3B,gDAAgD;IAChD,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,mDAAmD;IACnD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,qDAAqD;IACrD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gDAAgD;IAChD,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,mDAAmD;AACnD,MAAM,WAAW,uBAAuB;IACtC,gFAAgF;IAChF,MAAM,EAAE,MAAM,CAAC;IACf,6CAA6C;IAC7C,UAAU,CAAC,EAAE,GAAG,CAAC,SAAS,EAAE,CAAC;IAC7B,+BAA+B;IAC/B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,6BAA6B;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,8CAA8C;IAC9C,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,iEAAiE;IACjE,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,yGAAyG;IACzG,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED;;;;;;;GAOG;AACH,qBAAa,gBAAiB,YAAW,aAAa;IACpD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAkB;IAC9C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA+D;IAC7F,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAW;IAC1C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAU;gBAE3B,OAAO,EAAE,uBAAuB;IAe5C,2DAA2D;IAC3D,IAAI,WAAW,IAAI,OAAO,CAEzB;IAEK,YAAY,CAAC,GAAG,EAAE,eAAe,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;CAsDnE"}

package/dist/auth/jwt.js

@@ -0,0 +1,95 @@
+/**
+ * JWT Authenticator — verifies Bearer tokens and maps claims to Identity.
+ *
+ * Mirrors the Python `JWTAuthenticator` from apcore-mcp-python.
+ */
+import jwt from "jsonwebtoken";
+import { createIdentity } from "apcore-js";
+/**
+ * Authenticator that verifies JWT Bearer tokens from the Authorization header.
+ *
+ * Returns an Identity on success, or `null` if:
+ * - No Authorization header is present
+ * - The header is not a valid "Bearer <token>" format
+ * - The token fails verification (expired, wrong signature, etc.)
+ */
+export class JWTAuthenticator {
+    _secret;
+    _algorithms;
+    _audience;
+    _issuer;
+    _claimMapping;
+    _requireClaims;
+    _requireAuth;
+    constructor(options) {
+        this._secret = options.secret;
+        this._algorithms = options.algorithms ?? ["HS256"];
+        this._audience = options.audience;
+        this._issuer = options.issuer;
+        this._claimMapping = {
+            id: options.claimMapping?.id ?? "sub",
+            type: options.claimMapping?.type ?? "type",
+            roles: options.claimMapping?.roles ?? "roles",
+            attrs: options.claimMapping?.attrs,
+        };
+        this._requireClaims = options.requireClaims ?? ["sub"];
+        this._requireAuth = options.requireAuth ?? true;
+    }
+    /** Whether unauthenticated requests should be rejected. */
+    get requireAuth() {
+        return this._requireAuth;
+    }
+    async authenticate(req) {
+        const authHeader = req.headers.authorization;
+        if (!authHeader)
+            return null;
+        // Must be "Bearer <token>"
+        const parts = authHeader.split(" ");
+        if (parts.length !== 2 || parts[0].toLowerCase() !== "bearer")
+            return null;
+        const token = parts[1];
+        if (!token)
+            return null;
+        try {
+            const verifyOptions = {
+                algorithms: this._algorithms,
+            };
+            if (this._audience)
+                verifyOptions.audience = this._audience;
+            if (this._issuer)
+                verifyOptions.issuer = this._issuer;
+            const payload = jwt.verify(token, this._secret, verifyOptions);
+            // payload can be string (rare) or JwtPayload object
+            if (typeof payload === "string")
+                return null;
+            const claims = payload;
+            // Check required claims are present
+            for (const claim of this._requireClaims) {
+                if (!(claim in claims))
+                    return null;
+            }
+            const rawId = claims[this._claimMapping.id];
+            if (rawId === undefined || rawId === null)
+                return null;
+            const id = String(rawId);
+            const type = String(claims[this._claimMapping.type] ?? "user");
+            const rawRoles = claims[this._claimMapping.roles];
+            const roles = Array.isArray(rawRoles) ? rawRoles.map(String) : [];
+            // Extract attrs from payload
+            const attrs = {};
+            if (this._claimMapping.attrs) {
+                for (const key of this._claimMapping.attrs) {
+                    if (key in claims) {
+                        attrs[key] = claims[key];
+                    }
+                }
+            }
+            return createIdentity(id, type, roles, attrs);
+        }
+        catch {
+            // Verification failed (expired, invalid signature, etc.)
+            return null;
+        }
+    }
+}
+//# sourceMappingURL=jwt.js.map

package/dist/auth/jwt.js.map

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

package/dist/auth/storage.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Identity propagation via AsyncLocalStorage.
+ *
+ * Replaces Python's ContextVar pattern for propagating the authenticated
+ * identity through the async call chain without explicit parameter passing.
+ */
+import { AsyncLocalStorage } from "node:async_hooks";
+import type { Identity } from "apcore-js";
+/** AsyncLocalStorage instance that carries the current Identity through async scopes. */
+export declare const identityStorage: AsyncLocalStorage<Identity | null>;
+/**
+ * Get the current Identity from the async context.
+ *
+ * Returns `null` if called outside an `identityStorage.run()` scope
+ * or if the scope was entered with a `null` identity.
+ */
+export declare function getCurrentIdentity(): Identity | null;
+//# sourceMappingURL=storage.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../../src/auth/storage.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAE1C,yFAAyF;AACzF,eAAO,MAAM,eAAe,oCAA2C,CAAC;AAExE;;;;;GAKG;AACH,wBAAgB,kBAAkB,IAAI,QAAQ,GAAG,IAAI,CAEpD"}

package/dist/auth/storage.js

@@ -0,0 +1,19 @@
+/**
+ * Identity propagation via AsyncLocalStorage.
+ *
+ * Replaces Python's ContextVar pattern for propagating the authenticated
+ * identity through the async call chain without explicit parameter passing.
+ */
+import { AsyncLocalStorage } from "node:async_hooks";
+/** AsyncLocalStorage instance that carries the current Identity through async scopes. */
+export const identityStorage = new AsyncLocalStorage();
+/**
+ * Get the current Identity from the async context.
+ *
+ * Returns `null` if called outside an `identityStorage.run()` scope
+ * or if the scope was entered with a `null` identity.
+ */
+export function getCurrentIdentity() {
+    return identityStorage.getStore() ?? null;
+}
+//# sourceMappingURL=storage.js.map

package/dist/auth/storage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.js","sourceRoot":"","sources":["../../src/auth/storage.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAGrD,yFAAyF;AACzF,MAAM,CAAC,MAAM,eAAe,GAAG,IAAI,iBAAiB,EAAmB,CAAC;AAExE;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB;IAChC,OAAO,eAAe,CAAC,QAAQ,EAAE,IAAI,IAAI,CAAC;AAC5C,CAAC"}

package/dist/auth/types.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Authentication interfaces for apcore-mcp.
+ *
+ * Re-exports the Identity type from apcore-js and defines the
+ * Authenticator interface that transport-level auth implementations must satisfy.
+ */
+import type { IncomingMessage } from "node:http";
+import type { Identity } from "apcore-js";
+export type { Identity };
+/**
+ * Authenticator interface — implemented by auth strategies (e.g. JWT).
+ *
+ * `authenticate()` inspects incoming HTTP headers and returns an Identity
+ * for authenticated requests, or `null` for unauthenticated/invalid requests.
+ */
+export interface Authenticator {
+    authenticate(req: IncomingMessage): Promise<Identity | null>;
+    /** Whether unauthenticated requests should be rejected. Default true. */
+    readonly requireAuth?: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/auth/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AACjD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAG1C,YAAY,EAAE,QAAQ,EAAE,CAAC;AAEzB;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,YAAY,CAAC,GAAG,EAAE,eAAe,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAAC;IAC7D,yEAAyE;IACzE,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;CAChC"}

package/dist/auth/types.js

@@ -0,0 +1,8 @@
+/**
+ * Authentication interfaces for apcore-mcp.
+ *
+ * Re-exports the Identity type from apcore-js and defines the
+ * Authenticator interface that transport-level auth implementations must satisfy.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/auth/types.js.map

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

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAEA;;;;;;;GAOG;AAoCH,wBAAsB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAkH1C"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAEA;;;;;;;GAOG;AA4CH,wBAAsB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAgJ1C"}

package/dist/cli.js

@@ -10,7 +10,7 @@
 import { existsSync, statSync } from "node:fs";
 import { resolve } from "node:path";
 import { parseArgs } from "node:util";
-import { serve, VERSION } from "./index.js";
+import { serve, VERSION, JWTAuthenticator } from "./index.js";
 function printUsage() {
     console.log(`
 apcore-mcp v${VERSION} - Automatic MCP Server for apcore modules
@@ -31,6 +31,13 @@ Options:
   --explorer                 Enable the browser-based Tool Explorer UI (HTTP only)
   --explorer-prefix <path>   URL prefix for the explorer UI (default: /explorer)
   --allow-execute            Allow tool execution from the explorer UI
+  --jwt-secret <string>      JWT secret key for Bearer token authentication
+  --jwt-algorithm <alg>      JWT algorithm (default: HS256)
+  --jwt-audience <string>    Expected JWT audience claim
+  --jwt-issuer <string>      Expected JWT issuer claim
+  --jwt-require-auth         Require auth (default: true)
+  --jwt-permissive           Permissive mode: allow unauthenticated requests (overrides --jwt-require-auth)
+  --exempt-paths <paths>     Comma-separated paths exempt from auth (default: /health,/metrics)
   --help                     Show this help message
 `);
 }
@@ -53,6 +60,13 @@ export async function main() {
                 explorer: { type: "boolean", default: false },
                 "explorer-prefix": { type: "string", default: "/explorer" },
                 "allow-execute": { type: "boolean", default: false },
+                "jwt-secret": { type: "string" },
+                "jwt-algorithm": { type: "string" },
+                "jwt-audience": { type: "string" },
+                "jwt-issuer": { type: "string" },
+                "jwt-require-auth": { type: "boolean", default: true },
+                "jwt-permissive": { type: "boolean", default: false },
+                "exempt-paths": { type: "string" },
                 help: { type: "boolean", default: false },
             },
             strict: true,
@@ -116,10 +130,29 @@ export async function main() {
     }
     // Validate log-level
     const logLevel = values["log-level"];
-    const validLogLevels = ["DEBUG", "INFO", "WARNING", "ERROR"];
+    const validLogLevels = ["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"];
     if (logLevel && !validLogLevels.includes(logLevel)) {
         fail(`--log-level must be one of: ${validLogLevels.join(", ")}. Got '${logLevel}'.`);
     }
+    // Build JWT authenticator if --jwt-secret is provided
+    const jwtSecret = values["jwt-secret"];
+    const jwtRequireAuth = values["jwt-permissive"] ? false : values["jwt-require-auth"];
+    const authenticator = jwtSecret
+        ? new JWTAuthenticator({
+            secret: jwtSecret,
+            algorithms: values["jwt-algorithm"]
+                ? [values["jwt-algorithm"]]
+                : undefined,
+            audience: values["jwt-audience"],
+            issuer: values["jwt-issuer"],
+            requireAuth: jwtRequireAuth,
+        })
+        : undefined;
+    // Parse exempt paths
+    const exemptPathsRaw = values["exempt-paths"];
+    const exemptPaths = exemptPathsRaw
+        ? exemptPathsRaw.split(",").map((p) => p.trim())
+        : undefined;
     // Launch the MCP server
     try {
         await serve(registry, {
@@ -132,6 +165,8 @@ export async function main() {
             explorer: values.explorer,
             explorerPrefix: values["explorer-prefix"],
             allowExecute: values["allow-execute"],
+            authenticator,
+            exemptPaths,
         });
     }
     catch (error) {

package/dist/cli.js.map

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

package/dist/explorer/handler.d.ts

@@ -13,12 +13,16 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
 import type { Tool } from "@modelcontextprotocol/sdk/types.js";
 import type { ExecutionRouter } from "../server/router.js";
+import type { Authenticator } from "../auth/types.js";
+import type { Identity } from "apcore-js";
 /** Options for creating an ExplorerHandler. */
 export interface ExplorerHandlerOptions {
     /** Whether to allow tool execution from the explorer UI. Default: false */
     allowExecute?: boolean;
     /** URL prefix for the explorer. Default: "/explorer" */
     prefix?: string;
+    /** Optional authenticator for explorer POST calls. */
+    authenticator?: Authenticator;
 }
 export declare class ExplorerHandler {
     private readonly _toolsByName;
@@ -26,15 +30,20 @@ export declare class ExplorerHandler {
     private readonly _router;
     private readonly _allowExecute;
     private readonly _prefix;
+    private readonly _authenticator?;
     constructor(tools: Tool[], router: ExecutionRouter, options?: ExplorerHandlerOptions);
     /** The URL prefix this handler is mounted at. */
     get prefix(): string;
     /**
      * Attempt to handle an HTTP request.
      *
+     * @param req - The incoming HTTP request
+     * @param res - The server response
+     * @param url - The parsed URL
+     * @param identity - Pre-authenticated identity from transport layer (if any)
      * @returns true if the request was handled, false if it should be passed through
      */
-    handleRequest(req: IncomingMessage, res: ServerResponse, url: URL): Promise<boolean>;
+    handleRequest(req: IncomingMessage, res: ServerResponse, url: URL, identity?: Identity | null): Promise<boolean>;
     /**
      * Build a summary dict for a tool (used in the list endpoint).
      */

package/dist/explorer/handler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"handler.d.ts","sourceRoot":"","sources":["../../src/explorer/handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AACjE,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,oCAAoC,CAAC;AAC/D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAI3D,+CAA+C;AAC/C,MAAM,WAAW,sBAAsB;IACrC,2EAA2E;IAC3E,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,wDAAwD;IACxD,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAKD,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAoB;IACjD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAkB;IAC1C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAU;IACxC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;gBAG/B,KAAK,EAAE,IAAI,EAAE,EACb,MAAM,EAAE,eAAe,EACvB,OAAO,CAAC,EAAE,sBAAsB;IASlC,iDAAiD;IACjD,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED;;;;OAIG;IACG,aAAa,CACjB,GAAG,EAAE,eAAe,EACpB,GAAG,EAAE,cAAc,EACnB,GAAG,EAAE,GAAG,GACP,OAAO,CAAC,OAAO,CAAC;IA6CnB;;OAEG;IACH,OAAO,CAAC,YAAY;IAWpB;;OAEG;IACH,OAAO,CAAC,WAAW;IAYnB;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAWzB;;OAEG;YACW,eAAe;CAyD9B"}
+{"version":3,"file":"handler.d.ts","sourceRoot":"","sources":["../../src/explorer/handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AACjE,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,oCAAoC,CAAC;AAC/D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAG3D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAG1C,+CAA+C;AAC/C,MAAM,WAAW,sBAAsB;IACrC,2EAA2E;IAC3E,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,wDAAwD;IACxD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,sDAAsD;IACtD,aAAa,CAAC,EAAE,aAAa,CAAC;CAC/B;AAKD,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAoB;IACjD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAkB;IAC1C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAU;IACxC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAgB;gBAG9C,KAAK,EAAE,IAAI,EAAE,EACb,MAAM,EAAE,eAAe,EACvB,OAAO,CAAC,EAAE,sBAAsB;IAUlC,iDAAiD;IACjD,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED;;;;;;;;OAQG;IACG,aAAa,CACjB,GAAG,EAAE,eAAe,EACpB,GAAG,EAAE,cAAc,EACnB,GAAG,EAAE,GAAG,EACR,QAAQ,CAAC,EAAE,QAAQ,GAAG,IAAI,GACzB,OAAO,CAAC,OAAO,CAAC;IAwDnB;;OAEG;IACH,OAAO,CAAC,YAAY;IAWpB;;OAEG;IACH,OAAO,CAAC,WAAW;IAYnB;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAWzB;;OAEG;YACW,eAAe;CAmE9B"}