Release 0.8.1

Release version 0.8.1

See CHANGELOG.md for details.

Release 0.8.0

Added

• Approval system (F-028): Full runtime approval support via ElicitationApprovalHandler that bridges MCP elicitation to apcore's approval system. New approval_handler parameter on serve(). Supports request_approval() and check_approval() methods.
• ElicitationApprovalHandler: Presents approval requests to users via MCP elicitation. Maps elicit actions (accept/decline/cancel) to ApprovalResult statuses.
• CLI --approval flag with choices: elicit, auto-approve, always-deny, off (default).
• Approval error codes: APPROVAL_DENIED, APPROVAL_TIMEOUT, APPROVAL_PENDING added to ERROR_CODES.
• Enhanced error responses with AI guidance: ErrorMapper now extracts retryable, ai_guidance, user_fixable, and suggestion fields from apcore ModuleError and includes non-None values in error response dicts. ExecutionRouter appends AI guidance as structured JSON to error text content for AI agent consumption.
• AI intent metadata in tool descriptions: MCPServerFactory.build_tool() reads descriptor.metadata for AI intent keys (x-when-to-use, x-when-not-to-use, x-common-mistakes, x-workflow-hints) and appends them to tool descriptions for agent visibility.
• Streaming annotation: DEFAULT_ANNOTATIONS now includes streaming field. AnnotationMapper.to_description_suffix() includes streaming=true when the annotation is set.

Changed

• APPROVAL_TIMEOUT auto-retryable: ErrorMapper sets retryable=True for APPROVAL_TIMEOUT errors, signaling to AI agents that the operation can be retried.
• APPROVAL_PENDING includes approval_id: ErrorMapper extracts approval_id from error details for APPROVAL_PENDING errors.
• Error text content enriched: Router error text now includes AI guidance fields as a structured JSON appendix when present, enabling AI agents to parse retry/fix hints.

Release 0.7.0

Added

• JWT Authentication (F-027): Optional JWT-based authentication for HTTP transports (streamable-http, sse). New authenticator parameter on serve() and MCPServer. Validates Bearer tokens, maps JWT claims to apcore Identity, and injects identity into Context for ACL enforcement.
• JWTAuthenticator: Configurable JWT validation with ClaimMapping for flexible claim-to-Identity field mapping. Supports custom algorithms, audience, issuer, and required claims.
• AuthMiddleware: ASGI middleware that bridges HTTP authentication to MCP handlers via ContextVar[Identity]. Supports exempt_paths (exact match) and exempt_prefixes (prefix match) for unauthenticated endpoints.
• Authenticator Protocol: @runtime_checkable protocol for custom authentication backends.
• Permissive auth mode: require_auth=False parameter on serve() and MCPServer allows unauthenticated requests to proceed without identity instead of returning 401.
• exempt_paths parameter: serve() and MCPServer accept exempt_paths for exact-path authentication bypass (e.g. {"/health", "/metrics"}).
• CLI JWT flags: --jwt-secret, --jwt-algorithm, --jwt-audience, --jwt-issuer arguments for enabling JWT authentication from the command line.
• CLI --jwt-key-file: Read JWT verification key from a PEM file (e.g. RS256 public key). Takes priority over --jwt-secret and JWT_SECRET env var.
• CLI --jwt-require-auth / --no-jwt-require-auth: Toggle permissive auth mode from the command line.
• CLI --exempt-paths: Comma-separated list of paths exempt from authentication.
• JWT_SECRET env var fallback: CLI resolves JWT key in priority order: --jwt-key-file > --jwt-secret > JWT_SECRET environment variable.
• Explorer Authorization UI: Swagger-UI-style Authorization input field in the Tool Explorer. Paste a Bearer token to authenticate tool execution requests. Generated cURL commands automatically include the Authorization header.
• Explorer auth enforcement: When authenticator is set, tool execution via the Explorer returns 401 Unauthorized without a valid Bearer token. The Explorer UI displays a clear error message prompting the user to enter a token.
• Auth failure audit logging: AuthMiddleware emits a WARNING log with the request path on authentication failure.
• extract_headers() utility: Public helper to extract ASGI scope headers as a lowercase-key dict. Exported from apcore_mcp.auth.
• JWT authentication example: examples/run.py supports JWT_SECRET environment variable to demonstrate JWT authentication with a sample token.
• PyJWT dependency: Added PyJWT>=2.0 to project dependencies.

Changed

• Explorer UI layout: Redesigned from a bottom-panel layout to a Swagger-UI-style inline accordion. Each tool expands its detail, schema, and "Try it" section directly below the tool name. Only one tool can be expanded at a time. Detail is loaded once on first expand and cached.
• AuthMiddleware exempt_prefixes: Added exempt_prefixes parameter for prefix-based path exemption. Explorer paths are automatically exempt when both explorer and authenticator are enabled, so the Explorer UI always loads.
• extract_headers refactored: Moved from private AuthMiddleware._extract_headers() to module-level extract_headers() function for reuse in Explorer routes.

Release 0.6.0

Added

• Example modules: examples/ with 5 runnable demo modules — 3 class-based (text_echo, math_calc, greeting) and 2 binding.yaml (convert_temperature, word_count) — for quick Explorer UI demo out of the box.

Changed

• BREAKING: ExecutionRouter.handle_call() return type: Changed from (content, is_error) to (content, is_error, trace_id). Callers that unpack the 2-tuple must update to 3-tuple unpacking.
• BREAKING: Explorer /call response format: Changed from {"result": ...} / {"error": ...} to MCP-compliant CallToolResult format: {"content": [...], "isError": bool, "_meta": {"_trace_id": ...}}.

Fixed

• MCP protocol compliance: Router no longer injects _trace_id as a content block in tool results. trace_id is now returned as a separate tuple element and surfaced in Explorer responses via _meta. Factory handler raises exceptions for errors so the MCP SDK correctly sets isError=True.
• Explorer UI default values: defaultFromSchema() now correctly skips null defaults and falls through to type-based placeholders, fixing blank form fields for binding.yaml modules.

Release 0.5.1

Changed

• Rename Inspector to Explorer: Renamed the MCP Tool Inspector module to MCP Tool Explorer across the entire codebase — module path (apcore_mcp.inspector → apcore_mcp.explorer), CLI flags, Python API parameters, HTML UI, tests, README, and CHANGELOG. No functional changes; all endpoints and behavior remain identical.

Fixed

• Version test: Fixed test_run_uses_package_version_when_version_is_none to patch importlib.metadata.version so the test is not sensitive to the installed package version.

Release 0.5.0

Added

• MCP Tool Inspector (F-026): Optional browser-based UI for inspecting and testing MCP tools, mounted at /inspector when explorer=True. Includes 4 HTTP endpoints (GET /inspector/, GET /inspector/tools, GET /inspector/tools/<name>, POST /inspector/tools/<name>/call), a self-contained HTML/CSS/JS page with no external dependencies, configurable inspector_prefix, and allow_execute guard (default False). HTTP transports only; silently ignored for stdio.
• CLI Inspector flags: --explorer, --inspector-prefix, and --allow-execute arguments.
• Inspector UI: proactive execution status detection: The Inspector probes execution status on page load via a lightweight POST to /tools/__probe__/call, so the "Tool execution is disabled" message appears immediately instead of requiring a user click first.
• Inspector UI: URL-safe tool name encoding: Tool names in fetch URLs are wrapped with encodeURIComponent() to prevent malformed URLs when tool names contain special characters.
• Inspector UI: error handling on tool detail fetch: .catch() handler on the loadDetail fetch chain displays network errors in the detail panel instead of silently swallowing them.

Release 0.4.0

Release version 0.4.0

See CHANGELOG.md for details.

Release 0.3.0

Added

• trace_id passback: Every successful response now includes a second content item with _trace_id metadata for request tracing.
• validate_inputs: serve(validate_inputs=True) enables pre-execution input validation via Executor.validate(). Invalid inputs are rejected before module execution.
• Always-on Context: Context is now always created for every tool call, enabling trace_id generation even without MCP callbacks.

Changed

• SchemaExporter integration: MCPServerFactory.build_tool() now uses apcore.schema.exporter.SchemaExporter.export_mcp() for canonical MCP annotation mapping instead of duplicating logic.
• to_strict_schema() delegation: OpenAIConverter._apply_strict_mode() now delegates to apcore.schema.strict.to_strict_schema() instead of custom recursive implementation. This adds x-* extension stripping, oneOf/anyOf/allOf recursion, $defs recursion, and alphabetically sorted required lists.
• Dependency bump: Requires apcore>=0.5.0 (was >=0.2.0).

Removed

• Custom strict mode: Removed OpenAIConverter._apply_strict_recursive() in favor of to_strict_schema().

Release 0.2.0

Added

• MCPServer: Non-blocking MCP server wrapper for framework integrations with configurable transport and async event loop management.
• serve() hooks: on_startup and on_shutdown callbacks for lifecycle management.
• Health endpoint: Built-in health check support for HTTP-based transports.
• Constants module: Centralized REGISTRY_EVENTS, ErrorCodes, and MODULE_ID_PATTERN for consistent values across adapters and listeners.
• Module ID validation: Enhanced id_normalizer.normalize() with format validation using MODULE_ID_PATTERN.
• Exported building blocks: Public API exports for MCPServerFactory, ExecutionRouter, RegistryListener, and TransportManager.

Fixed

• MCP Tool metadata: Fixed use of _meta instead of meta in MCP Tool constructor for proper internal metadata handling.

Refactored

• Circular import resolution: Moved utility functions (resolve_registry, resolve_executor) to dedicated _utils.py module to prevent circular dependencies between __init__.py and server/server.py.

Release 0.1.0

Added

• Public API: serve() to launch an MCP Server from any apcore Registry or Executor.
• Public API: to_openai_tools() to export apcore modules as OpenAI-compatible tool definitions.
• CLI: apcore-mcp command with --extensions-dir, --transport, --host, --port, --name, --version, and --log-level options.
• Three transports: stdio (default), Streamable HTTP, and SSE.
• SchemaConverter: JSON Schema conversion with $ref/$defs inlining for MCP and OpenAI compatibility.
• AnnotationMapper: Maps apcore annotations (readonly, destructive, idempotent, open_world) to MCP ToolAnnotations.
• ErrorMapper: Sanitizes apcore errors for safe client exposure — no stack traces, no internal details leaked.
• ModuleIDNormalizer: Bijective dot-to-dash conversion for OpenAI function name compatibility.
• OpenAIConverter: Full registry-to-OpenAI conversion with strict mode (Structured Outputs) and embed_annotations support.
• MCPServerFactory: Creates MCP Server instances, builds Tool objects, and registers list_tools/call_tool handlers.
• ExecutionRouter: Routes MCP tool calls to apcore Executor with error sanitization.
• TransportManager: Manages stdio, Streamable HTTP, and SSE transport lifecycle.
• RegistryListener: Thread-safe dynamic tool registration via registry.on("register"/"unregister") callbacks.
• Structured logging: All components use logging.getLogger(__name__) under the apcore_mcp namespace.
• Dual input: Both serve() and to_openai_tools() accept either a Registry or Executor instance.
• Filtering: tags and prefix parameters for selective module exposure.
• 260 tests: Unit, integration, E2E, performance, and security test suites.