Support Codex plugin/MCP loading in addition to Claude plugin marketplace

[jay-swk]

Summary

Nova works as a Claude marketplace plugin today, but it is not directly usable from Codex even when the MCP server is installed locally.

Current behavior

• Claude can load Nova from the marketplace and start the local MCP server through .mcp.json.
• The installed Nova plugin includes a working MCP entry at ~/.claude/plugins/marketplaces/nova-marketplace/.mcp.json.
• The MCP server bundle exists locally at mcp-server/dist/index.js.
• In Codex, the MCP server is not exposed automatically because Nova does not currently ship Codex-compatible plugin metadata.

Why this matters

Users who already installed Nova locally may expect it to be reusable in Codex, but today it appears disconnected even though the MCP server itself is present and runnable.

Expected behavior

Nova should be installable or discoverable in Codex without requiring users to manually copy plugin files into each workspace.

Suggested improvements

1. Add Codex plugin manifest support, e.g. .codex-plugin/plugin.json.
2. Provide Codex-compatible MCP metadata so Codex can load the same Nova MCP server officially.
3. Document a supported Codex installation path/workflow.
4. Prefer a source-of-truth setup in the Nova repo itself rather than per-workspace local shims.

Notes

This looks less like an MCP-server problem and more like a packaging/distribution gap between Claude plugin format and Codex plugin format.

If helpful, I can follow up with a proposed file layout for Codex support.

[jay-swk]

Phase 1 구현 완료 — v5.1.0 릴리스

Release v5.1.0 에 Codex CLI 듀얼 매니페스트 지원을 추가했습니다.

이슈 본문 매핑

제안	상태	비고
1. .codex-plugin/plugin.json 추가	✅ Done	skills 경로 공유 (./.claude/skills/), 기존 Claude 매니페스트와 독립
2. Codex-compatible MCP metadata	✅ Done	.codex-plugin/.mcp.json 추가 (stdio, 상대경로)
3. Codex 설치 경로/워크플로우 문서화	✅ Done	README / README.ko Codex CLI (Beta) 섹션 — ~/.agents/plugins/nova/ 설치 컨벤션 준수
4. Source-of-truth in repo (per-workspace shim 제거)	✅ Done	.codex-plugin/ 리포 자체에 체크인

설계 원칙

기존 Claude 사용자 사이드이펙트 0 을 최우선 제약으로 구현했습니다. .claude-plugin/, 루트 .mcp.json, hooks/session-start.sh, .claude/{commands,agents,skills}/ 파일은 단 한 줄도 수정하지 않았습니다 (git diff --stat 0).

설계서: docs/designs/codex-dual-manifest.md

미완 (Phase 2/3 — 별도 스코프)

Phase 1 에서 의도적으로 제외한 범위:

• Phase 2: Claude commands 12개 → Codex skill wrapper, Claude agents 5개 → .codex/agents/*.toml 변환. Codex는 slash command/agent type 네이티브 지원이 없어 Nova 기능의 상당 부분이 Codex 에서는 미가용 상태입니다.
• Phase 3: 실제 Codex 환경에서 .codex-plugin/.mcp.json 의 상대경로 (./mcp-server/dist/index.js) 가 로드되는지 실측 미완. 실측 실패 시 ~/.codex/config.toml 절대경로 fallback 으로 전환이 필요합니다. README 에 fallback 안내는 이미 포함되어 있습니다.
• session-start.sh: Codex 는 SessionStart hook 개념이 없어 Nova 의 Always-On 자동 규칙 주입이 동작하지 않습니다. 이 손실은 README 에 명시했습니다.

이슈 상태

실환경 Codex 검증(Phase 3) 이 완료될 때까지 이슈는 열어둡니다. Codex 에서 Nova MCP 가 로드되는 로그/스크린샷을 공유해주시거나 동작 이슈를 확인해주시면, fallback 가이드 보강 또는 경로 전략 변경으로 대응하겠습니다.

follow-up 제안하신 "proposed file layout for Codex support" 가 있으시면 이 스레드에 남겨주세요. 🙏

[jay-swk]

Phase 3 실환경 검증 결과

실제 Codex (Mac 앱) 환경에서 v5.1.0을 설치해 동작을 검증했다. 결과를 공유한다.

설치 절차 (재현용)

# 1) 클론
git clone https://github.com/TeamSPWK/nova.git ~/.agents/plugins/nova
cd ~/.agents/plugins/nova && git checkout v5.1.0

# 2) MCP 서버 빌드
cd mcp-server && pnpm install && pnpm build

# 3) Personal marketplace 등록
cat > ~/.agents/plugins/marketplace.json <<'JSON'
{
  "name": "personal",
  "interface": { "displayName": "Personal Plugins" },
  "plugins": [{
    "name": "nova",
    "source": { "source": "local", "path": "./nova" },
    "policy": { "installation": "AVAILABLE", "authentication": "ON_INSTALL" },
    "category": "Development"
  }]
}
JSON

# 4) MCP 전역 등록 (스킬 전역 활성화가 안 되는 케이스 대비)
cat >> ~/.codex/config.toml <<'TOML'
[mcp_servers.nova]
command = "node"
args = ["/Users/<YOU>/.agents/plugins/nova/mcp-server/dist/index.js"]
TOML

실환경에서 발견한 제약

Phase 1 설계 당시 예상했던 것보다 Codex 플러그인 활성화 메커니즘이 더 엄격하다.

1. Personal marketplace 등록만으로는 플러그인이 활성화되지 않는다

~/.agents/plugins/marketplace.json에 installation: AVAILABLE로 등록해도 Codex는 "설치 가능"으로만 표시한다. 사용자가 Codex 앱의 /plugins UI에서 명시적으로 Install 버튼을 눌러야 실제 활성화된다. README에 이 단계를 명시해야 한다.

2. .agents/skills/가 프로젝트 루트에 있으면 스킬이 project-scoped가 된다

실측 중에 발견한 현상: 개발 중인 Nova 리포(/Users/jay/develop/nova)에 로컬 상태로 생성된 .agents/skills/ 디렉토리가 있었는데, Codex가 이 디렉토리를 project-scoped로 인식해 Nova 리포 안에서만 스킬이 @로 노출되고 다른 프로젝트에서는 안 보였다. 이는 ~/.agents/plugins/marketplace.json을 통한 personal plugin 활성화와 무관하게 발생한다.

3. MCP 상대경로 (./mcp-server/dist/index.js)는 검증 불가 상태

플러그인이 UI에서 Install되지 않은 상태에서는 .codex-plugin/.mcp.json의 상대경로가 로드되는지 독립적으로 확인할 수 없었다. 전역 ~/.codex/config.toml의 절대경로 방식을 병행해야 MCP 도구 11개(get_rules, get_state, x_verify, orchestration_* 등)가 모든 프로젝트에서 사용 가능하다.

권장 설치 경로 (차기 README 업데이트 예정)

목표	권장 설정
MCP 도구를 모든 프로젝트에서 사용	~/.codex/config.toml에 [mcp_servers.nova] 절대경로 등록
스킬 7개를 모든 프로젝트에서 @nova로 호출	Codex 앱 /plugins UI에서 Nova를 Install
특정 프로젝트 전용	해당 리포에 .agents/skills/를 두면 project-scoped 활성화

Phase 2 여부

commands 12개와 agents 5개를 Codex skill wrapper/TOML로 변환하는 Phase 2는 진행 여부 미정. 지금은 MCP + skills만으로도 Nova의 핵심 검증 기능이 Codex에서 동작하므로, 실수요 확인 후 결정하려 한다. commands 변환을 원하시는 분은 별도 코멘트 부탁드린다.

다음 작업 (별도 PR 예정)

• README의 Codex 설치 섹션 보강: /plugins UI Install 절차 명시, MCP 전역 등록을 정식 경로로 승격
• ~/.codex/config.toml 수동 편집 대신 설치 헬퍼 스크립트 제공 검토 (scripts/install-codex.sh)

이슈는 README 보강 PR 머지 시까지 열어둔다.