Skip to content

install.md

Latest commit

 

History

History
134 lines (92 loc) · 4.31 KB

install.md

File metadata and controls

134 lines (92 loc) · 4.31 KB
Raw

Installation

This repository is designed for Codex API mode and documents a Windows-first install path.

Prerequisites

  • Codex Desktop or another Codex environment that supports local plugins
  • A local clone of this repository
  • Python 3.11+ if you plan to use km-confluence-drawio
  • Node.js with npx if you plan to use gitlab-mcp or the draw.io server inside km-confluence-drawio

Environment variables you may need:

  • For gitlab-mcp
    • GITLAB_PERSONAL_ACCESS_TOKEN
    • GITLAB_API_URL
  • For km-confluence-drawio
    • CONFLUENCE_PERSONAL_TOKEN
    • optional CONFLUENCE_SPACES_FILTER
    • optional CONFLUENCE_URL if you want to override the default Lenovo KM host

1. Clone the repository

Example:

git clone https://github.com/balloon72/codex-api-plugins.git
cd .\codex-api-plugins

2. Register the marketplace in Codex

Run the installer from the repository root:

powershell -ExecutionPolicy Bypass -File .\scripts\install-home-local.ps1

What the script does:

  • resolves the repo root
  • updates ~/.codex/config.toml
  • registers the local marketplace codex-api-plugins
  • enables gitlab-mcp@codex-api-plugins
  • enables km-confluence-drawio@codex-api-plugins
  • removes the stale github-gh@codex-api-plugins block if it exists
  • creates a timestamped backup before writing changes

3. Restart Codex

Completely close Codex Desktop and launch it again.

4. Verify that the plugins are visible

Open the plugin picker or plugin management UI and look for:

  • GitLab MCP
  • KM Confluence + Draw.io

If they do not appear, see troubleshooting.md.

5. Configure GitLab environment variables

If you will use gitlab-mcp, configure:

[Environment]::SetEnvironmentVariable('GITLAB_PERSONAL_ACCESS_TOKEN', '<your-token>', 'User')
[Environment]::SetEnvironmentVariable('GITLAB_API_URL', 'https://gitlab.example.com/api/v4', 'User')

Notes:

  • GITLAB_API_URL must point to the REST root and end in /api/v4.
  • Restart Codex Desktop after changing user environment variables.
  • Recommended token scopes:
    • api for review-note drafts, publish flows, and other write actions
    • read_api for read-only summaries and inspection

6. Configure KM environment variables

km-confluence-drawio defaults CONFLUENCE_URL to Lenovo KM, so most users only need a token and, optionally, a space filter:

[Environment]::SetEnvironmentVariable('CONFLUENCE_PERSONAL_TOKEN', '<your-km-token>', 'User')
[Environment]::SetEnvironmentVariable('CONFLUENCE_SPACES_FILTER', 'DCIM', 'User')

Optional override if you intentionally target another Confluence host:

[Environment]::SetEnvironmentVariable('CONFLUENCE_URL', 'https://your-confluence.example.com', 'User')

Notes:

  • CONFLUENCE_SPACES_FILTER is optional. Remove it or leave it unset if you want cross-space reads.
  • Restart Codex Desktop after updating environment variables.
  • The bundled KM MCP server is read-first.
  • Large upload/sync helper scripts are still legacy utilities. They are not yet unified to the CONFLUENCE_PERSONAL_TOKEN model used by km-mcp, so do not assume those script-backed write flows will work with only a KM personal token.

Optional: manual config update

The install script is the supported path, but the equivalent config shape is:

[marketplaces.codex-api-plugins]
last_updated = "2026-06-01T00:00:00Z"
source_type = "local"
source = '\\?\C:\path\to\codex-api-plugins'

[plugins."gitlab-mcp@codex-api-plugins"]
enabled = true

[plugins."km-confluence-drawio@codex-api-plugins"]
enabled = true

Notes:

  • Replace the path with your actual repository path.
  • Keep the extended Windows path prefix \\?\.
  • Use any valid UTC RFC3339 timestamp for last_updated.
  • gitlab-mcp still requires its GitLab environment variables.
  • km-confluence-drawio still requires CONFLUENCE_PERSONAL_TOKEN.

Optional: repo-local reuse

If you want to reuse one of these plugins in another repository:

  1. Copy plugins/gitlab-mcp/ or plugins/km-confluence-drawio/ into the target repository under plugins/
  2. Copy the matching entry from .agents/plugins/marketplace.json
  3. Register that target repository as the marketplace source in the target Codex environment

This repository itself is optimized for the home-local install flow above.