Skip to content

repo-local.md

Latest commit

 

History

History
135 lines (94 loc) · 5.28 KB

repo-local.md

File metadata and controls

135 lines (94 loc) · 5.28 KB
Raw

Repo-local installation for OpenCode

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

Supported contract

The consumer repository should have:

  • an opencode.json
  • a local wrapper in tools/modly_mcp/run_server.mjs
  • an OpenCode skills.paths entry pointing to node_modules/modly-cli-mcp/skills
  • optionally tools/_tmp/modly_mcp/local.env

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.

In this supported repo-local flow, OpenCode can also discover the packaged skills automatically from the installed package. The supported path is exactly node_modules/modly-cli-mcp/skills configured through skills.paths.

Not supported

  • pointing opencode.json to the source checkout of modly_CLI_MCP
  • executing node /path/to/checkout/src/mcp/server.mjs from the consumer repository
  • depending on OpenCode 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 opencode.json

Configure OpenCode to invoke the local wrapper and discover packaged skills automatically:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "modly": {
      "type": "local",
      "enabled": true,
      "timeout": 30000,
      "command": [
        "node",
        "tools/modly_mcp/run_server.mjs"
      ]
    }
  },
  "skills": {
    "paths": [
      "node_modules/modly-cli-mcp/skills"
    ]
  }
}

Canonical repo-local template shipped in this package:

That opencode.json lives in the consumer repository. It must not reference files inside the source checkout of modly_CLI_MCP.

What is ready automatically in this supported repo-local flow:

  • tools/modly_mcp/run_server.mjs resolves the installed modly-mcp binary local-first.
  • OpenCode discovers modly-cli-mcp skills from node_modules/modly-cli-mcp/skills through skills.paths.
  • The consumer repository does not need to copy the skills manually.

4) 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.

5) 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, but this flow does not give you the same repo-local skills.paths contract automatically because there is no supported package-relative node_modules/modly-cli-mcp/skills location to point at from the consumer repo.
  • Repo-local: better when each repository needs to pin its own package version.

If you want the global flow, use docs/install/global.md. If you want the Codex variant of this same repo-local flow, use docs/install/codex-repo-local.md.