oct.mcp.server Namespace Reference

Classes
class	RateLimiter
class	ServerState

Functions
None	_dbg (*args, **kwargs)
ServerState	get_server_state ()
Path	_resolve_project_root (str|Path|None root_arg)
None	start_server (str|Path|None project_root=None, str|None profile=None, Path|None config_path=None, str transport="stdio", str host="127.0.0.1", int port=3001, int|None metrics_port=None)
list	_load_debug_config_patterns (Path root, McpConfig config)

Detailed Description

Purpose
-------
MCP server core (Layers 1 + orchestration) for the ``oct-mcp`` server.
Creates a :class:`mcp.server.fastmcp.FastMCP` instance, binds it to a
validated project root (Layer 1 — Gateway), and exposes the nine Phase
5A read-only tools via :mod:`oct.mcp.tools`.

Responsibilities
----------------
- Implement :func:`start_server`: resolve + validate project root,
  load config, instantiate all pipeline layers, register tools, run.
- Implement the token-bucket rate limiter (Layer 1) via
  :class:`RateLimiter`.
- Expose ``_server_state`` for tools to access the shared pipeline
  instances (singleton pattern: one server = one context).

Diagnostics
-----------
Domain: MCP
Levels:
    L1 — errors: startup failures, workspace binding failures
    L2 — lifecycle: server start/stop, workspace bound
    L3 — request details
    L4 — deep trace

Contracts
---------
- :func:`start_server` raises ``SystemExit(1)`` on fatal startup errors
  (invalid project root, no ``oct`` command) so ``__main__.py`` can
  propagate a clean exit code.
- The rate limiter is per-server-instance (not per-session), which is
  sufficient for the stdio Phase 5A transport where one server process
  handles one client session.
- ``_server_state`` is set before :meth:`FastMCP.run` is called and is
  available to all tool handlers during their execution.

Function Documentation

_dbg()

None oct.mcp.server._dbg ( * args, ** kwargs )

protected

Definition at line 63 of file server.py.

Here is the caller graph for this function:

_load_debug_config_patterns()

list oct.mcp.server._load_debug_config_patterns ( Path root, McpConfig config )

protected

Load ``redaction_patterns`` from ``debug_config.json`` if trusted.

Only reads the project-level debug config when
``config.trust_repo_config`` is ``True`` and the profile is not
``"airgapped"`` or ``"strict"``.

Returns an empty list (safe default) on any read/parse failure.

Definition at line 363 of file server.py.

Here is the call graph for this function:

Here is the caller graph for this function:

_resolve_project_root()

Path oct.mcp.server._resolve_project_root ( str | Path | None root_arg )

protected

Resolve and validate the project root directory.

Parameters
----------
root_arg
    Path provided via ``--project-root`` CLI argument, or ``None``
    to auto-discover from the current working directory.

Returns
-------
Resolved absolute :class:`Path`.

Raises
------
SystemExit(1)
    If the directory does not exist or is not a directory.

Definition at line 166 of file server.py.

Here is the call graph for this function:

Here is the caller graph for this function:

get_server_state()

ServerState oct.mcp.server.get_server_state

(

)

Return the current :class:`ServerState`.

Raises ``RuntimeError`` if called outside a running server context
(i.e. before :func:`start_server` has initialised the state).

Definition at line 147 of file server.py.

start_server()

None oct.mcp.server.start_server	(	str | Path | None	project_root = None,
		str | None	profile = None,
		Path | None	config_path = None,
		str	transport = "stdio",
		str	host = "127.0.0.1",
		int	port = 3001,
		int | None	metrics_port = None )

Initialise and run the ``oct-mcp`` server.

Steps:

1. Resolve and validate project root (Layer 1 — Gateway).
2. Load :class:`McpConfig` (with env var overrides).
3. Apply centralised policy overrides (Phase 5C, M-C7).
4. Override profile if ``--profile`` CLI arg was provided.
5. Instantiate all pipeline layers.
6. Start Prometheus metrics server (optional, Phase 5C).
7. Create FastMCP server.
8. Set ``_server_state`` singleton.
9. Register 9 read-only (Phase 5A) + 11 write (Phase 5B) tools.
10. Run the FastMCP server (stdio or SSE transport).

Parameters
----------
project_root
    Project root path override (``None`` = auto-discover).
profile
    MCP profile override (``None`` = use config file / env var).
config_path
    Path to the ``~/.oct-mcp/config.json`` config file
    (``None`` = use default location).
transport
    MCP transport: ``"stdio"`` (default) or ``"sse"``
    (HTTP/Server-Sent Events for remote access).
host
    Host to bind for SSE transport (default ``"127.0.0.1"``).
    Only used when *transport* is ``"sse"``.
port
    Port to bind for SSE transport (default ``3001``).
    Only used when *transport* is ``"sse"``.
metrics_port
    If set, starts a Prometheus ``/metrics`` server on this port.
    Overrides ``config.metrics_port``. Requires ``oct[metrics]``.

Definition at line 216 of file server.py.

Here is the call graph for this function: