OpenVibeCoding/docs/mcp/index.html at aa28d3d29198e9bb2d3cbd12d3ad9be9d6c3fb69 · xiaojiou176-open/OpenVibeCoding · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>CortexPilot | Read-only MCP quickstart</title>
    <meta
      name="description"
      content="Read-only MCP quickstart for CortexPilot: what the current Model Context Protocol surface exposes, who should use it first, and where the frozen write boundary remains."
    />
    <meta
      name="keywords"
      content="CortexPilot, MCP, Model Context Protocol, read-only MCP, Codex MCP, Claude Code MCP, OpenClaw MCP, workflow inspection"
    />
    <link rel="canonical" href="https://xiaojiou176-open.github.io/CortexPilot-public/mcp/" />
    <meta property="og:title" content="CortexPilot | Read-only MCP quickstart" />
    <meta
      property="og:description"
      content="Read-only MCP quickstart for CortexPilot across runs, Workflow Cases, approvals, compare, proof, and incident summaries."
    />
    <meta property="og:url" content="https://xiaojiou176-open.github.io/CortexPilot-public/mcp/" />
    <meta property="og:type" content="article" />
    <meta property="og:image" content="../assets/storefront/social-preview-1280x640.png" />
    <meta name="twitter:card" content="summary_large_image" />
    <meta name="twitter:title" content="CortexPilot | Read-only MCP quickstart" />
    <meta
      name="twitter:description"
      content="Truthful read-only MCP quickstart for CortexPilot, plus the current frozen write boundary."
    />
    <meta name="twitter:image" content="../assets/storefront/social-preview-1280x640.png" />
    <script type="application/ld+json">
      {
        "@context": "https://schema.org",
        "@type": "TechArticle",
        "headline": "CortexPilot read-only MCP quickstart",
        "url": "https://xiaojiou176-open.github.io/CortexPilot-public/mcp/",
        "description": "Truthful read-only MCP quickstart for CortexPilot across runs, Workflow Cases, approvals, compare, proof, and incident summaries."
      }
    </script>
    <script type="application/ld+json">
      {
        "@context": "https://schema.org",
        "@type": "FAQPage",
        "mainEntity": [
          {
            "@type": "Question",
            "name": "Is the current CortexPilot MCP surface read-only?",
            "acceptedAnswer": {
              "@type": "Answer",
              "text": "Yes. The current public MCP contract is read-only. It exposes machine-readable inspection over runs, Workflow Cases, approvals, compare, proof, and incident summaries without enabling write-capable mutation."
            }
          },
          {
            "@type": "Question",
            "name": "Who should open the MCP quickstart first?",
            "acceptedAnswer": {
              "@type": "Answer",
              "text": "Teams should start here when their first question is about protocol-level inspection, machine-readable workflow truth, or how external tools can safely read CortexPilot state before they touch API or builder packages."
            }
          },
          {
            "@type": "Question",
            "name": "Does this page imply write-capable MCP or hosted operator accounts?",
            "acceptedAnswer": {
              "@type": "Answer",
              "text": "No. The page explains the current read-only MCP contract only. It does not imply write-capable MCP, hosted operator accounts, or a replacement for the orchestration runtime."
            }
          }
        ]
      }
    </script>
    <style>
      :root {
        color-scheme: light;
        --bg: #f4efe7;
        --panel: #fffaf2;
        --ink: #17232c;
        --muted: #536370;
        --line: rgba(23, 35, 44, 0.12);
        --accent: #1f5d75;
        --accent-soft: rgba(31, 93, 117, 0.1);
        --warn: #92400e;
        --warn-soft: rgba(146, 64, 14, 0.1);
        --shadow: 0 22px 52px rgba(23, 35, 44, 0.1);
      }

      * { box-sizing: border-box; }

      body {
        margin: 0;
        background:
          radial-gradient(circle at top left, rgba(31, 93, 117, 0.1), transparent 28%),
          linear-gradient(180deg, #f8f3eb 0%, #efe6da 100%);
        color: var(--ink);
        font: 16px/1.65 "Inter", "Segoe UI", system-ui, sans-serif;
      }

      main {
        max-width: 1080px;
        margin: 0 auto;
        padding: 40px 20px 72px;
      }

      a { color: var(--accent); }
      a:hover { color: #12485c; }

      .hero,
      .section,
      .table-shell {
        background: var(--panel);
        border: 1px solid var(--line);
        border-radius: 28px;
        box-shadow: var(--shadow);
      }

      .hero,
      .section {
        padding: 28px;
      }

      .section { margin-top: 24px; }

      .eyebrow,
      .badge {
        display: inline-flex;
        width: fit-content;
        padding: 7px 12px;
        border-radius: 999px;
        font-size: 13px;
        font-weight: 700;
      }

      .eyebrow {
        background: rgba(23, 35, 44, 0.08);
        color: var(--muted);
      }

      .badge.primary { background: var(--accent-soft); color: var(--accent); }
      .badge.warn { background: var(--warn-soft); color: var(--warn); }

      h1, h2, h3 { margin: 0; line-height: 1.15; }
      h1 { font-size: clamp(2.4rem, 4.2vw, 3.9rem); max-width: 12ch; }
      h2 { font-size: 1.7rem; margin-bottom: 12px; }
      p, li, td { color: var(--muted); }
      .lede { font-size: 1.08rem; max-width: 78ch; }

      .mini-nav,
      .actions {
        display: flex;
        flex-wrap: wrap;
        gap: 12px;
      }

      .button {
        display: inline-flex;
        align-items: center;
        justify-content: center;
        padding: 12px 16px;
        border-radius: 999px;
        text-decoration: none;
        font-weight: 600;
      }

      .button.primary { background: var(--accent); color: white; }
      .button.secondary {
        border: 1px solid var(--line);
        background: white;
        color: var(--ink);
      }

      .grid {
        display: grid;
        grid-template-columns: repeat(auto-fit, minmax(230px, 1fr));
        gap: 16px;
      }

      .card {
        border: 1px solid var(--line);
        border-radius: 22px;
        background: white;
        padding: 18px;
      }

      .table-shell {
        margin-top: 24px;
        overflow: hidden;
      }

      table {
        width: 100%;
        border-collapse: collapse;
      }

      th, td {
        padding: 14px 16px;
        border-bottom: 1px solid var(--line);
        text-align: left;
        vertical-align: top;
      }

      th {
        font-size: 13px;
        letter-spacing: 0.03em;
        text-transform: uppercase;
        background: rgba(23, 35, 44, 0.04);
      }

      tr:last-child td { border-bottom: none; }

      code {
        background: rgba(23, 35, 44, 0.06);
        border-radius: 6px;
        padding: 2px 6px;
        font-family: "SFMono-Regular", Menlo, monospace;
      }

      pre {
        overflow-x: auto;
        padding: 16px;
        border-radius: 18px;
        background: #f1f5f8;
      }
    </style>
  </head>
  <body>
    <main>
      <section class="hero">
        <span class="eyebrow">Read-only protocol quickstart</span>
        <nav class="mini-nav" aria-label="Top navigation">
          <a href="../">Back to the public landing page</a>
          <a href="../compatibility/">Compatibility matrix</a>
          <a href="../agent-starters/">Agent starter kits</a>
          <a href="../ai-surfaces/">AI + MCP + API surfaces</a>
          <a href="../integrations/">Integration guide</a>
          <a href="../skills/">Skills quickstart</a>
          <a href="../api/">API and contract quickstart</a>
          <a href="../builders/">Builder quickstart</a>
        </nav>
        <h1>Read-only MCP quickstart.</h1>
        <p class="lede">
          CortexPilot already exposes a real <strong>Model Context Protocol (MCP)</strong> surface, but the public contract is intentionally
          <strong>read-only</strong>. This page exists so teams searching for MCP, Codex, Claude Code, or OpenClaw adoption paths can find the truthful protocol story quickly instead of guessing from source files.
        </p>
        <p class="lede">
          Use this page when your first question is: <strong>“What can external tools safely inspect right now?”</strong>
          If your first question is instead about package imports, builder bootstrap, or repo-owned skills, this page should route you to the better next click.
        </p>
        <div class="actions">
          <a class="button primary" href="#fast-adoption-path">Open the protocol path</a>
          <a class="button secondary" href="../compatibility/">Open compatibility matrix</a>
          <a class="button secondary" href="../agent-starters/">Open agent starter kits</a>
          <a class="button secondary" href="../api/">Open API quickstart</a>
          <a class="button secondary" href="../integrations/">Open integration guide</a>
          <a class="button secondary" href="../skills/">Open skills quickstart</a>
        </div>
      </section>

      <section class="section">
        <h2>What the current MCP surface is for</h2>
        <div class="grid">
          <article class="card">
            <span class="badge primary">Inspection</span>
            <h3>Read workflow truth</h3>
            <p>Inspect runs, Workflow Cases, approvals, compare outputs, proof packs, and incident summaries without mutating anything.</p>
          </article>
          <article class="card">
            <span class="badge primary">Machine-readable</span>
            <h3>Return structured JSON</h3>
            <p>Expose a repo-owned protocol boundary that other tools and agents can consume safely instead of screen-scraping dashboard pages.</p>
          </article>
          <article class="card">
            <span class="badge warn">Boundary</span>
            <h3>Stay below execution authority</h3>
            <p>Keep operator truth readable without inventing a second control plane, a hosted account layer, or write-capable MCP claims.</p>
          </article>
        </div>
      </section>

      <section class="section" id="fast-adoption-path">
        <h2>Fast adoption path</h2>
        <div class="table-shell">
          <table>
            <thead>
              <tr>
                <th>My first question</th>
                <th>Start here</th>
                <th>Why</th>
              </tr>
            </thead>
            <tbody>
              <tr>
                <td>I need the shortest truthful protocol boundary</td>
                <td>This page</td>
                <td>Use MCP first when your team needs machine-readable inspection before packages or builder code.</td>
              </tr>
              <tr>
                <td>I need the “which adoption ladder fits us?” answer</td>
                <td><a href="../compatibility/">Compatibility matrix</a></td>
                <td>Use it when the main question is whether you should start from MCP, skills, builders, or proof-first cases.</td>
              </tr>
              <tr>
                <td>I also need HTTP, types, or a thin JS client</td>
                <td><a href="../api/">API and contract quickstart</a></td>
                <td>Use the API page when you want the route/type/client edge in addition to the protocol story.</td>
              </tr>
              <tr>
                <td>I need repo-owned builder packages</td>
                <td><a href="../builders/">Builder quickstart</a></td>
                <td>Use it when you are ready to import package-level helpers rather than only understand the protocol boundary.</td>
              </tr>
              <tr>
                <td>I need coding-agent team guidance</td>
                <td><a href="../integrations/">Integration guide</a> and <a href="../skills/">skills quickstart</a></td>
                <td>Use these when your real question is how a Codex / Claude Code / OpenClaw team should adopt the repo truthfully.</td>
              </tr>
            </tbody>
          </table>
        </div>
      </section>

      <section class="section">
        <h2>Try the current server</h2>
        <p>
          The current server is a repo-owned <strong>stdio JSON-RPC</strong> node. Run it from the repo root when you want the shortest proof that the public MCP story is real:
        </p>
        <pre><code>PYTHONPATH=apps/orchestrator/src python3 -m cortexpilot_orch.cli mcp-readonly-server</code></pre>
        <p>
          Current tool set:
          <code>list_runs</code>,
          <code>get_run</code>,
          <code>get_run_events</code>,
          <code>get_run_reports</code>,
          <code>list_workflows</code>,
          <code>get_workflow</code>,
          <code>list_queue</code>,
          <code>get_pending_approvals</code>,
          <code>get_diff_gate_state</code>,
          <code>get_compare_summary</code>,
          <code>get_proof_summary</code>,
          and <code>get_incident_summary</code>.
        </p>
        <p>
          Want the client-specific config files after you prove the server is
          real? Open the <a href="../agent-starters/">agent starter kits</a>
          for tracked Codex / Claude Code / OpenClaw setup snippets.
        </p>
      </section>

      <section class="section">
        <h2>What to hand to any stdio-capable MCP client</h2>
        <p>
          If your client asks for a command, arguments, working directory, and environment instead of a hosted URL, use these repo-owned values directly.
        </p>
        <div class="table-shell">
          <table>
            <thead>
              <tr>
                <th>Field</th>
                <th>Use this value</th>
                <th>Why</th>
              </tr>
            </thead>
            <tbody>
              <tr>
                <td><strong>Transport</strong></td>
                <td><code>stdio</code></td>
                <td>The shipped public MCP surface is a repo-owned stdio JSON-RPC server, not a hosted MCP account.</td>
              </tr>
              <tr>
                <td><strong>Working directory</strong></td>
                <td>the CortexPilot repo root</td>
                <td>The server reads repo-local runtime state, run bundles, and workflow truth.</td>
              </tr>
              <tr>
                <td><strong>Environment</strong></td>
                <td><code>PYTHONPATH=apps/orchestrator/src</code></td>
                <td>This exposes the orchestrator module path without inventing a separate package install story.</td>
              </tr>
              <tr>
                <td><strong>Command</strong></td>
                <td><code>python3 -m cortexpilot_orch.cli mcp-readonly-server</code></td>
                <td>This is the truthful command surface wired by the repo today.</td>
              </tr>
            </tbody>
          </table>
        </div>
      </section>

      <section class="section">
        <h2>What it does not do yet</h2>
        <ul>
          <li>no write-capable MCP mutations</li>
          <li>no hosted operator account or managed login layer</li>
          <li>no claim that MCP replaces the orchestration runtime itself</li>
        </ul>
      </section>

      <section class="section">
        <h2>Why this matters for different audiences</h2>
        <div class="grid">
          <article class="card">
            <span class="badge primary">Codex</span>
            <h3>Protocol-first inspection</h3>
            <p>Useful when a Codex-facing workflow needs one machine-readable place to inspect workflow truth before promoting package or skills adoption.</p>
          </article>
          <article class="card">
            <span class="badge primary">Claude Code</span>
            <h3>MCP-compatible workflow context</h3>
            <p>Useful when a Claude Code team wants the protocol layer to stay honest about what can be read today without implying write-enabled MCP.</p>
          </article>
          <article class="card">
            <span class="badge primary">OpenClaw</span>
            <h3>Adjacent protocol layer</h3>
            <p>Useful as a read-oriented integration boundary around OpenClaw workflows, while plugin-ready wording stays separate from the current MCP story.</p>
          </article>
        </div>
      </section>

      <section class="section">
        <h2>Where to read the current contract</h2>
        <ul>
          <li><a href="https://github.com/xiaojiou176-open/CortexPilot-public/blob/main/apps/orchestrator/src/cortexpilot_orch/mcp_readonly_server.py">read-only MCP server implementation</a></li>
          <li><a href="https://github.com/xiaojiou176-open/CortexPilot-public/blob/main/apps/orchestrator/README.md">orchestrator README</a></li>
          <li><a href="https://github.com/xiaojiou176-open/CortexPilot-public/blob/main/docs/architecture/mcp-and-operator-copilot-v1.md">MCP architecture baseline</a></li>
          <li><a href="../ai-surfaces/">AI + MCP + API surfaces</a> for the broader product map</li>
        </ul>
      </section>
    </main>
  </body>
</html>