Skip to content

codex-repo-local.md

Latest commit

 

History

History
114 lines (74 loc) · 4.3 KB

codex-repo-local.md

File metadata and controls

114 lines (74 loc) · 4.3 KB
Raw

Repo-local installation for Codex

Use this guide when you want a consumer repository to control its own installation of modly-cli-mcp for Codex.

Supported contract

The consumer repository should have:

  • a .codex/config.toml
  • a local wrapper in tools/modly_mcp/run_server.mjs
  • optionally tools/_tmp/modly_mcp/local.env
  • a trusted project entry in Codex so project-scoped .codex/config.toml is loaded

The wrapper resolves node_modules/.bin/modly-mcp in the consumer repository first and falls back to a global modly-mcp in PATH only if the local one is missing. In other words, the supported resolution order is local-first with global-fallback.

Not supported

  • pointing Codex at the source checkout of modly_CLI_MCP
  • executing node /path/to/checkout/src/mcp/server.mjs from the consumer repository
  • depending on Codex cwd to discover binaries or configuration files

1) Install the package in the consumer repository

Example with npm:

npm install -D modly-cli-mcp

If your internal distribution uses a tarball, install that .tgz instead of the registry package name.

2) Copy the canonical wrapper

Copy this file from the package into your consumer repository:

The script computes the repository root from import.meta.url, not from cwd.

3) Create .codex/config.toml

Configure Codex to invoke the local wrapper:

[mcp_servers.modly]
command = "node"
args = ["tools/modly_mcp/run_server.mjs"]

Template shipped in this package:

That .codex/config.toml lives in the consumer repository. It must not reference files inside the source checkout of modly_CLI_MCP.

4) Trust the project

Codex loads project-scoped .codex/config.toml only in trusted projects. Mark the consumer repository as trusted in your Codex setup before relying on this repo-local configuration.

5) Optional local configuration

If the consumer repository needs local-only variables, create this optional file:

tools/_tmp/modly_mcp/local.env

Minimum supported format:

# comments and blank lines are ignored
MODLY_API_URL=http://127.0.0.1:8765

Important notes:

  • The wrapper uses a minimal built-in parser; it does not use dotenv.
  • It only accepts KEY=VALUE lines.
  • It merges those variables over process.env only for the child process.
  • The file is optional and local to the consumer repository.

6) Verify resolution without starting MCP

node tools/modly_mcp/run_server.mjs --check

--check only validates resolution/configuration and reports whether it would use local or global mode. It does not call /health, start the MCP server, install anything, or mutate files.

Runtime notes

  • Execution surface taxonomy:
    • workflow-run / process-run and modly.workflowRun.* / modly.processRun.* are the visible canonical run primitive surfaces.
    • modly.capability.execute and modly.recipe.execute are orchestration wrapper surfaces over those run primitives; recovery/polling stays on the canonical run status surfaces.
    • generate / job and modly.job.status remain legacy compatibility surfaces.
  • FastAPI-backed surfaces use MODLY_API_URL (default http://127.0.0.1:8765).
  • capabilities and process-runs use the Electron automation bridge on :8766.
  • The installed package derives those bridge URLs automatically unless you override them explicitly.
  • modly.recipe.execute is experimental, opt-in, hidden by default, and disabled unless the wrapper environment sets MODLY_EXPERIMENTAL_RECIPE_EXECUTE=1.
  • Without MODLY_EXPERIMENTAL_RECIPE_EXECUTE, the recipe tool is not advertised in the public MCP catalog.

If you need experimental recipe execution in a consumer repository, add the flag to the wrapper environment explicitly:

MODLY_EXPERIMENTAL_RECIPE_EXECUTE=1

When to choose global vs repo-local

  • Global: simpler if one environment uses a single installed version in PATH.
  • Repo-local: better when each repository needs to pin its own package version.

If you want the global flow, use docs/install/codex-global.md.