Metadata-Version: 2.4
Name: nexus-sphere-mcp
Version: 0.2.0
Summary: Nexus Sphere AI Meeting for coding agents: a multi-AI second opinion inside Claude Code, Codex and Cursor (MCP server + CLI).
Author: Nexus Sphere
License: Proprietary
Project-URL: Homepage, https://nexus-sphere-two.vercel.app/developers
Project-URL: Documentation, https://nexus-sphere-two.vercel.app/developers
Keywords: mcp,model-context-protocol,claude-code,codex,cursor,code-review,multi-agent,llm
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: License :: Other/Proprietary License
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: httpx<1,>=0.27
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"

# nexus-sphere-mcp — Nexus の AI会議を Claude Code・Codex・Cursor から

コーディングエージェントの**相棒**として、複数の AI（別々の会社のモデル）に
独立に考えさせ、反論し合わせ、**結論・一致・相違・各AIの要点・出典**を返す
MCP サーバーと CLI。エージェントが自分の答えに自信を持てないとき、行動する前に
「セカンドオピニオン」を取れる。

*A multi-AI second opinion inside your coding agent: several models from different
vendors answer independently, rebut each other, and you get the conclusion, where
they agree, where they disagree, each model's position and cited sources.*

## 2分で使う / Quick start

1. **API キーを発行する** — Nexus にログインし、設定 → API キー
   （`/settings/api-keys`）で `deliberate` スコープのキーを作る。`nxs_…` で始まる。
2. **エージェントに登録する**（Python 3.11+ と [uv](https://docs.astral.sh/uv/) が必要）

```bash
export NEXUS_API_KEY=nxs_...   # シェルの設定に入れておく
```

**Claude Code**

```bash
claude mcp add --transport stdio --env NEXUS_API_KEY=$NEXUS_API_KEY nexus -- uvx --from "git+https://github.com/nexus-core-jp/Nexus-sphere#subdirectory=cli" nexus-sphere-mcp
```

**Cursor**（`.cursor/mcp.json` またはグローバルの `~/.cursor/mcp.json`）

```json
{
  "mcpServers": {
    "nexus": {
      "command": "uvx",
      "args": ["--from","git+https://github.com/nexus-core-jp/Nexus-sphere#subdirectory=cli","nexus-sphere-mcp"],
      "env": { "NEXUS_API_KEY": "${env:NEXUS_API_KEY}" }
    }
  }
}
```

**Codex CLI**（`~/.codex/config.toml`）

```toml
[mcp_servers.nexus]
command = "uvx"
args = ["--from","git+https://github.com/nexus-core-jp/Nexus-sphere#subdirectory=cli","nexus-sphere-mcp"]
env_vars = ["NEXUS_API_KEY"]
# 合議は 1〜3 分かかる。既定の 60 秒だと途中で切られる
tool_timeout_sec = 300
```

3. **頼む** — 例: 「この修正案を Nexus の second_opinion にかけて、反対意見があれば教えて」

`nexus mcp-config` が同じ設定を出す（`--installed` でインストール済みの `nexus` を使う形）。

## 道具 / Tools

| 道具 | 何をするか |
|:--|:--|
| `second_opinion` | **エージェント自身の答え・計画・修正案**を複数の AI に批評させる。誤り・危険な前提・代替案と、各 AI の採否（そのまま採用 / 条件付き / 採用すべきでない） |
| `deliberate` | 判断を仰ぐ問いを AI会議にかける（設計の選択、トレードオフ、事実確認が要る問い） |
| `review_diff` | 送る前の差分レビュー。危険度、2社以上が一致した「直せ」、1社だけの異論、見ていない範囲 |
| `get_result` | 待ちきれなかった合議の結果を trace_id で受け取る（新しい合議は始めない・無料） |

共通の引数: `context`（背景・コード片）、`participants`（優先する AI。例
`["claude","openai","gemini"]`）、`web_search`（`auto` / `on` / `off`）、
`mode`（`quick` / `balanced` / `deep`）、`language`（`ja` / `en`）。

## 送るもの / What is sent

**道具の引数に渡した文字列だけ。** ファイルは読まない。例外は `review_diff` の
`source: "git"` で、利用者がそれを頼んだときだけ今のリポジトリの `git diff` を送る。
入力には上限がある（問い 4,000 字、背景 20,000 字、提案 12,000 字、差分 400,000 字）。
上限を越えたものは切らずに断る。

## 料金 / Pricing

1 回の `deliberate` / `second_opinion` / `review_diff` は、あなたのプランの
**AI会議 1 回**として数える（組織の月の枠・支出上限に掛かる）。`get_result` は
数えない。API キー 1 本あたり 1 時間 30 回の上限もある（漏れた鍵で月の枠を
焼き切らないため）。

## 時間 / Timing

合議は 1〜3 分かかる。サーバーは最大 240 秒待ち、クライアントが `progressToken`
を付けていれば進捗を通知する。それを越えたら trace_id を返すので、`get_result`
で受け取る（**同じ問いを送り直すと二重に課金される**）。

- Claude Code: 道具の締切は `MCP_TOOL_TIMEOUT`（ミリ秒）。短く設定している場合は
  `MCP_TOOL_TIMEOUT=300000` 以上に
- Codex: `tool_timeout_sec = 300`（上の設定例に入れてある。既定は 60 秒）
- 待つ秒数は `NEXUS_MCP_MAX_WAIT`（または `nexus-sphere-mcp --max-wait 50`）で変えられる。
  クライアントの締切より短くしておくと、切られる前に trace_id を返せる

## 環境変数 / Environment

| 変数 | 既定 | 意味 |
|:--|:--|:--|
| `NEXUS_API_KEY` | — | API キー（必須。`nexus login` で保存したものでも可） |
| `NEXUS_API_URL` | `https://nexus-sphere-api.onrender.com` | API の場所 |
| `NEXUS_MCP_MAX_WAIT` | `240` | 1 回の呼び出しで結果を待つ秒数 |
| `NEXUS_APP_URL` | `https://nexus-sphere-two.vercel.app` | 案内に出す画面の URL |

## CLI

同じパッケージに `nexus` コマンドも入る（`uv tool install nexus-sphere-mcp` か
`pipx install nexus-sphere-mcp`）。

```
nexus login                 # 設定 → API キー で発行したキーを貼る
nexus review                # ブランチの差分（PR と同じ範囲）を合議にかける
nexus review --working-tree # コミット前の変更全体を合議にかける
nexus pr                    # 合議 → 確認 → gh で PR 作成（判定を本文に付ける）
nexus outcome merged        # Webhook が無い配備で、顛末を手で返す
nexus stats                 # 予測と顛末の突き合わせ
nexus backtest --limit 100  # 過去の PR で判定を採点する
```

### 判定の読み方

- **危険度** low / medium / high。1社でも確信を持って high と言えば high。
  2社以上が独立に「マージ前に直せ」と言った指摘があれば、誰も high と言って
  いなくても high。
- **一致した指摘 / 異論** は分けて出る。合議の価値は異論の側にある。
- **合議が見た範囲** は必ず出る。大きな差分は全部は見られない。
- `nexus review` の終了コードは、high のとき 2。CI やフックで止められる。

### 顛末が返る仕組み

`nexus pr` は PR 本文の末尾に `<!-- nexus-review: <id> -->` を埋める。設定 → API キー
の画面にある GitHub Webhook をリポジトリに登録すると、マージ・CI の失敗・Revert が
自動で同じ記録に積まれる。Webhook を置けない環境では `nexus outcome <status>`。

### 設定

`~/.config/nexus-sphere/config.json`（0600）。環境変数 `NEXUS_API_URL` /
`NEXUS_API_KEY` が優先。`NEXUS_CONFIG_DIR` で置き場所を変えられる。

## 開発 / Development

```bash
cd cli
PYTHONPATH=. python -m pytest tests -q -o addopts=""
```

配布の手順は `docs/MCP_PUBLISHING.md`。
