install_mcp Namespace Reference

Functions
None	_dbg (*args, **kwargs)
dict	_make_oct_mcp_entry (Path project_root)
list[Path]	_get_host_config_paths (str host)
str|None	_detect_host (Path project_root)
dict	_read_json_safe (Path path)
dict	_merge_server_entry (dict config, dict server_entry)
int	run_install_mcp (str host, Path project_root, bool dry_run=True)

Variables
tuple	SUPPORTED_HOSTS = ("claude-code", "cursor", "vscode")

Detailed Description

Purpose
-------
Implements the ``oct install-mcp`` CLI subcommand. Detects the target
AI host (Claude Code, Cursor, VS Code, or ``auto``) and writes (or
previews) the ``oct-mcp`` server entry into the host's MCP config file.

Responsibilities
----------------
- Define :data:`MCP_HOSTS` mapping each supported host to its config
  file location(s) and the JSON schema for the ``oct-mcp`` entry.
- Implement :func:`run_install_mcp` which detects the host config path,
  merges the ``oct-mcp`` server entry, and writes the result (or
  previews it in dry-run mode).
- Print a human-readable summary of what was / would be changed.

Diagnostics
-----------
Domain: OCT-CLI
Levels:
    L2 — lifecycle: file read, file written

Contracts
---------
- This module does not import ``click`` or any MCP SDK.
- Writes only to known, allowlisted config file paths — never to
  arbitrary locations (design decision D-5B-7).
- ``dry_run=True`` (the default) never modifies any file.
- If the host config file already contains an ``oct-mcp`` server entry,
  the entry is updated in-place without duplicating it.

Function Documentation

_dbg()

None install_mcp._dbg ( * args, ** kwargs )

protected

Definition at line 47 of file install_mcp.py.

Here is the caller graph for this function:

_detect_host()

str | None install_mcp._detect_host ( Path project_root )

protected

Auto-detect the first installed host whose config file exists.

Definition at line 100 of file install_mcp.py.

Here is the call graph for this function:

Here is the caller graph for this function:

_get_host_config_paths()

list[Path] install_mcp._get_host_config_paths ( str host )

protected

Return candidate config file paths for *host* in preference order.

Definition at line 75 of file install_mcp.py.

Here is the caller graph for this function:

_make_oct_mcp_entry()

dict install_mcp._make_oct_mcp_entry ( Path project_root )

protected

Return the oct-mcp server entry for the current Python executable.

Definition at line 58 of file install_mcp.py.

Here is the caller graph for this function:

_merge_server_entry()

dict install_mcp._merge_server_entry ( dict config, dict server_entry )

protected

Merge the oct-mcp server entry into *config*.

For Claude Code ``settings.json`` the schema is::

    {"mcpServers": {"oct-mcp": {...}}}

For Cursor / VS Code ``mcp.json`` the schema is::

    {"servers": {"oct-mcp": {...}}}

If the key ``"mcpServers"`` is present (or the file is a Claude Code
settings.json) we use the Claude Code schema; otherwise we use the
Cursor/VS Code schema.

Definition at line 123 of file install_mcp.py.

Here is the caller graph for this function:

_read_json_safe()

dict install_mcp._read_json_safe ( Path path )

protected

Read JSON from *path*, returning ``{}`` on any error.

Definition at line 115 of file install_mcp.py.

Here is the caller graph for this function:

run_install_mcp()

int install_mcp.run_install_mcp	(	str	host,
		Path	project_root,
		bool	dry_run = True )

Install or preview the oct-mcp server entry for the given host.

Parameters
----------
host
    One of ``"claude-code"``, ``"cursor"``, ``"vscode"``, or
    ``"auto"`` (auto-detect).
project_root
    Absolute project root path (used as ``--project-root`` arg in
    the server entry).
dry_run
    When ``True`` (the default), print what would be written without
    modifying any files.

Returns
-------
Exit code: 0 on success, 1 on failure.

Definition at line 157 of file install_mcp.py.

Here is the call graph for this function:

Variable Documentation

SUPPORTED_HOSTS

tuple install_mcp.SUPPORTED_HOSTS = ("claude-code", "cursor", "vscode")

Definition at line 72 of file install_mcp.py.