feat: Add resource handlers for documentation in MCPServerFactory

- Implemented `register_resource_handlers` method to register handlers for listing and reading resources with documentation.
- Updated `MCPServerFactory` to include resource handlers in server initialization.
- Enhanced error handling in `ExecutionRouter` for better logging and context management.
- Introduced metrics endpoint in `TransportManager` for Prometheus compatibility.
- Updated tests to cover new resource handling functionality and metrics endpoint.
- Refactored existing tests for clarity and consistency, ensuring proper coverage for new features.

Author: tercel

CHANGELOG.md

@@ -9,6 +9,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- **metrics_collector parameter**: `serve(metrics_collector=...)` accepts a `MetricsCollector` instance to enable Prometheus metrics export.
+- **`/metrics` Prometheus endpoint**: HTTP-based transports (`streamable-http`, `sse`) now serve a `/metrics` route returning Prometheus text format when a `metrics_collector` is provided. Returns 404 when no collector is configured.
 - **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.

README.md

@@ -197,17 +197,41 @@ Exit codes: `0` normal, `1` invalid arguments, `2` startup failure.
 from apcore_mcp import serve
 
 serve(
-    registry_or_executor,       # Registry or Executor
-    transport="stdio",          # "stdio" | "streamable-http" | "sse"
-    host="127.0.0.1",          # host for HTTP transports
-    port=8000,                  # port for HTTP transports
-    name="apcore-mcp",         # server name
-    version=None,              # defaults to package version
+    registry_or_executor,        # Registry or Executor
+    transport="stdio",           # "stdio" | "streamable-http" | "sse"
+    host="127.0.0.1",           # host for HTTP transports
+    port=8000,                   # port for HTTP transports
+    name="apcore-mcp",          # server name
+    version=None,                # defaults to package version
+    on_startup=None,             # callback before transport starts
+    on_shutdown=None,            # callback after transport completes
+    tags=None,                   # filter modules by tags
+    prefix=None,                 # filter modules by ID prefix
+    log_level=None,              # logging level ("DEBUG", "INFO", etc.)
+    validate_inputs=False,       # validate inputs against schemas
+    metrics_collector=None,      # MetricsCollector for /metrics endpoint
 )
 ```
 
 Accepts either a `Registry` or `Executor`. When a `Registry` is passed, an `Executor` is created automatically.
 
+### `/metrics` Prometheus Endpoint
+
+When `metrics_collector` is provided to `serve()`, a `/metrics` HTTP endpoint is exposed that returns metrics in Prometheus text exposition format.
+
+- **Available on HTTP-based transports only** (`streamable-http`, `sse`). Not available with `stdio` transport.
+- **Returns Prometheus text format** with Content-Type `text/plain; version=0.0.4; charset=utf-8`.
+- **Returns 404** when no `metrics_collector` is configured.
+
+```python
+from apcore.observability import MetricsCollector
+from apcore_mcp import serve
+
+collector = MetricsCollector()
+serve(registry, transport="streamable-http", metrics_collector=collector)
+# GET http://127.0.0.1:8000/metrics -> Prometheus text format
+```
+
 ### `to_openai_tools()`
 
 ```python

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "apcore-mcp"
-version = "0.3.0"
+version = "0.4.0"
 description = "Automatic MCP Server & OpenAI Tools Bridge for apcore"
 readme = "README.md"
 license = "Apache-2.0"
@@ -25,7 +25,7 @@ classifiers = [
     "Topic :: Scientific/Engineering :: Artificial Intelligence",
 ]
 dependencies = [
-    "apcore>=0.5.0",
+    "apcore>=0.6.0",
     "mcp>=1.0.0,<2.0",
 ]
 

src/apcore_mcp/__init__.py

@@ -18,13 +18,14 @@
 from apcore_mcp.server.listener import RegistryListener
 from apcore_mcp.server.router import ExecutionRouter
 from apcore_mcp.server.server import MCPServer
-from apcore_mcp.server.transport import TransportManager
+from apcore_mcp.server.transport import MetricsExporter, TransportManager
 
 __all__ = [
     # Public API
     "serve",
     "to_openai_tools",
     # Server building blocks
+    "MetricsExporter",
     "MCPServer",
     "MCPServerFactory",
     "ExecutionRouter",
@@ -48,9 +49,9 @@
     "MCP_ELICIT_KEY",
 ]
 
-logger = logging.getLogger(__name__)
+__version__ = "0.4.0"
 
-__version__ = "0.3.0"
+logger = logging.getLogger(__name__)
 
 
 def serve(
@@ -63,8 +64,12 @@ def serve(
     version: str | None = None,
     on_startup: Callable[[], None] | None = None,
     on_shutdown: Callable[[], None] | None = None,
+    tags: list[str] | None = None,
+    prefix: str | None = None,
+    log_level: str | None = None,
     dynamic: bool = False,
     validate_inputs: bool = False,
+    metrics_collector: MetricsExporter | None = None,
 ) -> None:
     """Launch an MCP Server that exposes all apcore modules as tools.
 
@@ -77,20 +82,43 @@ def serve(
         version: MCP server version. Defaults to apcore-mcp version.
         on_startup: Optional callback invoked after setup, before transport starts.
         on_shutdown: Optional callback invoked after the transport completes.
+        tags: Filter modules by tags. Only modules with ALL specified tags are exposed.
+        prefix: Filter modules by ID prefix.
+        log_level: Set the log level for the apcore_mcp logger (e.g. "DEBUG", "INFO").
         dynamic: Reserved for future dynamic tool registration support.
         validate_inputs: Validate tool inputs against schemas before execution.
+        metrics_collector: Optional MetricsCollector for Prometheus /metrics endpoint.
     """
+    if not name:
+        raise ValueError("name must not be empty")
+    if len(name) > 255:
+        raise ValueError(f"name exceeds maximum length of 255: {len(name)}")
+    if tags is not None:
+        for tag in tags:
+            if not tag:
+                raise ValueError("Tag values must not be empty")
+    if prefix is not None and not prefix:
+        raise ValueError("prefix must not be empty")
+    if log_level is not None:
+        valid_levels = {"DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"}
+        if log_level.upper() not in valid_levels:
+            raise ValueError(f"Unknown log level: {log_level!r}. Valid: {sorted(valid_levels)}")
+
     version = version or __version__
 
+    if log_level is not None:
+        logging.getLogger("apcore_mcp").setLevel(getattr(logging, log_level.upper()))
+
     registry = resolve_registry(registry_or_executor)
     executor = resolve_executor(registry_or_executor)
 
     # Build MCP server components
     factory = MCPServerFactory()
     server = factory.create_server(name=name, version=version)
-    tools = factory.build_tools(registry)
+    tools = factory.build_tools(registry, tags=tags, prefix=prefix)
     router = ExecutionRouter(executor, validate_inputs=validate_inputs)
     factory.register_handlers(server, tools, router)
+    factory.register_resource_handlers(server, registry)
     init_options = factory.build_init_options(server, name=name, version=version)
 
     logger.info(
@@ -102,14 +130,16 @@ def serve(
     )
 
     # Select and run transport
-    transport_manager = TransportManager()
+    transport_lower = transport.lower()
+    transport_manager = TransportManager(metrics_collector=metrics_collector)
+    transport_manager.set_module_count(len(tools))
 
     async def _run() -> None:
-        if transport == "stdio":
+        if transport_lower == "stdio":
             await transport_manager.run_stdio(server, init_options)
-        elif transport == "streamable-http":
+        elif transport_lower == "streamable-http":
             await transport_manager.run_streamable_http(server, init_options, host=host, port=port)
-        elif transport == "sse":
+        elif transport_lower == "sse":
             await transport_manager.run_sse(server, init_options, host=host, port=port)
         else:
             raise ValueError(f"Unknown transport: {transport!r}. Expected 'stdio', 'streamable-http', or 'sse'.")

src/apcore_mcp/adapters/annotations.py

@@ -4,6 +4,14 @@
 
 from typing import Any
 
+DEFAULT_ANNOTATIONS = {
+    "readonly": False,
+    "destructive": False,
+    "idempotent": False,
+    "requires_approval": False,
+    "open_world": True,
+}
+
 
 class AnnotationMapper:
     """Maps apcore ModuleAnnotations to MCP ToolAnnotations format.
@@ -63,14 +71,21 @@ def to_description_suffix(self, annotations: Any | None) -> str:
         if annotations is None:
             return ""
 
-        # Build annotation key-value pairs
-        parts = [
-            f"readonly={str(annotations.readonly).lower()}",
-            f"destructive={str(annotations.destructive).lower()}",
-            f"idempotent={str(annotations.idempotent).lower()}",
-            f"requires_approval={str(annotations.requires_approval).lower()}",
-            f"open_world={str(annotations.open_world).lower()}",
-        ]
+        # Build annotation key-value pairs only for non-default values
+        parts = []
+        if annotations.readonly != DEFAULT_ANNOTATIONS["readonly"]:
+            parts.append(f"readonly={str(annotations.readonly).lower()}")
+        if annotations.destructive != DEFAULT_ANNOTATIONS["destructive"]:
+            parts.append(f"destructive={str(annotations.destructive).lower()}")
+        if annotations.idempotent != DEFAULT_ANNOTATIONS["idempotent"]:
+            parts.append(f"idempotent={str(annotations.idempotent).lower()}")
+        if annotations.requires_approval != DEFAULT_ANNOTATIONS["requires_approval"]:
+            parts.append(f"requires_approval={str(annotations.requires_approval).lower()}")
+        if annotations.open_world != DEFAULT_ANNOTATIONS["open_world"]:
+            parts.append(f"open_world={str(annotations.open_world).lower()}")
+
+        if not parts:
+            return ""
 
         return f"\n\n[Annotations: {', '.join(parts)}]"
 

src/apcore_mcp/adapters/errors.py

@@ -47,9 +47,10 @@ def to_mcp_error(self, error: Exception) -> dict[str, Any]:
 
     def _handle_apcore_error(self, error: Exception) -> dict[str, Any]:
         """Handle known apcore errors."""
-        code = error.code
-        message = error.message
-        details = error.details if error.details is not None else None
+        code: str = getattr(error, "code", "UNKNOWN")
+        message: str = getattr(error, "message", str(error))
+        raw_details: Any = getattr(error, "details", None)
+        details: dict[str, Any] | None = raw_details if raw_details is not None else None
 
         # Convert internal errors to generic message
         if code in self._INTERNAL_ERROR_CODES:
@@ -99,4 +100,4 @@ def _format_validation_errors(self, errors: list[dict[str, Any]]) -> str:
             msg = err.get("message", "invalid")
             error_lines.append(f"{field}: {msg}")
 
-        return "Schema validation failed: " + "; ".join(error_lines)
+        return "Schema validation failed:\n" + "\n".join(f"  {line}" for line in error_lines)

src/apcore_mcp/adapters/schema.py

@@ -5,6 +5,8 @@
 import copy
 from typing import Any
 
+_MAX_REF_DEPTH = 32
+
 
 class SchemaConverter:
     """Converts apcore ModuleDescriptor schemas to MCP-compatible schemas.
@@ -73,6 +75,7 @@ def _inline_refs(
         schema: dict[str, Any],
         defs: dict[str, Any],
         _seen: set[str] | None = None,
+        _depth: int = 0,
     ) -> dict[str, Any]:
         """Recursively inline all $ref references, removing $defs.
 
@@ -81,13 +84,17 @@ def _inline_refs(
             defs: Dictionary of definitions from $defs
             _seen: Internal set tracking visited $ref paths to prevent
                 infinite recursion on circular references.
+            _depth: Current recursion depth for safety limit.
 
         Returns:
             Schema with all $refs replaced by their definitions
 
         Raises:
-            ValueError: If a circular $ref is detected.
+            ValueError: If a circular $ref is detected or depth exceeds limit.
         """
+        if _depth > _MAX_REF_DEPTH:
+            raise ValueError(f"$ref resolution exceeded maximum depth of {_MAX_REF_DEPTH}")
+
         if _seen is None:
             _seen = set()
 
@@ -100,19 +107,19 @@ def _inline_refs(
                 _seen = _seen | {ref_path}
                 resolved = self._resolve_ref(ref_path, defs)
                 # Recursively inline refs in the resolved schema
-                return self._inline_refs(resolved, defs, _seen)
+                return self._inline_refs(resolved, defs, _seen, _depth + 1)
 
             # Otherwise, recursively process all values
             result = {}
             for key, value in schema.items():
                 if key == "$defs":
                     # Skip $defs, we'll remove it later
                     continue
-                result[key] = self._inline_refs(value, defs, _seen)
+                result[key] = self._inline_refs(value, defs, _seen, _depth + 1)
             return result
         elif isinstance(schema, list):
             # Recursively process list items
-            return [self._inline_refs(item, defs, _seen) for item in schema]
+            return [self._inline_refs(item, defs, _seen, _depth + 1) for item in schema]
         else:
             # Primitive value, return as-is
             return schema
@@ -139,7 +146,7 @@ def _resolve_ref(self, ref_path: str, defs: dict[str, Any]) -> dict[str, Any]:
         def_name = ref_path[8:]  # Remove "#/$defs/"
 
         if def_name not in defs:
-            raise ValueError(f"Definition not found: {def_name}")
+            raise KeyError(f"Definition not found: {def_name}")
 
         # Return a deep copy to avoid circular reference issues
         return copy.deepcopy(defs[def_name])