okstra 0.220.0 → 0.221.0

package/runtime/python/okstra_ctl/file_size_cap.py

@@ -0,0 +1,142 @@
+"""File-size thresholds for source and test files an implementation stage writes.
+
+Every later agent that touches a file loads all of it into context, so a stage that
+grows one file past a few hundred lines makes every following run pay for it. Both
+thresholds are measured on the stage diff: 300 lines is the target, reported as an
+advisory finding, and 400 lines is the limit, a blocking finding the correction round
+fixes by splitting the file (`_implementation-deliverable.md` §"Correction round").
+
+A line is a physical line, as `wc -l` and an editor's line numbers count it, plus an
+unterminated last line. The cost being capped is what an agent reads, and comments and
+blank lines are read too; it also lets the executor check the number with any tool.
+
+Only source and test files are capped: the extensions in `self_mock_signals.EXT_TO_LANG`,
+the languages okstra's coding preflight has rules for. Lockfiles, JSON / YAML data,
+snapshots, Markdown, SQL and config fall outside by extension. Inside that set, vendored,
+fixture, snapshot, generated and `.okstra` paths are exempt, and so is a file whose head
+declares itself generated.
+"""
+from __future__ import annotations
+
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path, PurePosixPath
+
+from .self_mock_signals import EXT_TO_LANG
+
+FILE_LINE_TARGET = 300
+FILE_LINE_LIMIT = 400
+
+_EXEMPT_SEGMENTS = frozenset({
+    ".okstra", "node_modules", "vendor", "fixtures", "__fixtures__", "__snapshots__",
+    "generated", "__generated__",
+})
+_GENERATED_MARKERS = (b"@generated", b"do not edit")
+_MARKER_HEAD_LINES = 5
+
+
+@dataclass(frozen=True)
+class FileSizeViolation:
+    path: str
+    before: int | None
+    after: int
+    kind: str
+    threshold: int
+
+    @property
+    def blocking(self) -> bool:
+        return self.threshold == FILE_LINE_LIMIT
+
+    @property
+    def finding_id(self) -> str:
+        prefix = "FILE-SIZE" if self.blocking else "FILE-SIZE-ADVISORY"
+        return f"{prefix}:{self.path}"
+
+    def line(self) -> str:
+        before = "new" if self.before is None else str(self.before)
+        label = "limit" if self.blocking else "target"
+        return (
+            f"{self.finding_id}:{self.threshold + 1} {before}->{self.after} lines "
+            f"({self.kind}; {label} {self.threshold})"
+        )
+
+
+def capped_path(path: str) -> bool:
+    """True when the cap applies to this repository-relative path."""
+    pure = PurePosixPath(path)
+    if EXT_TO_LANG.get(pure.suffix) is None or ".min." in pure.name:
+        return False
+    return not any(part in _EXEMPT_SEGMENTS for part in pure.parts[:-1])
+
+
+def physical_lines(data: bytes) -> int:
+    return data.count(b"\n") + (1 if data and not data.endswith(b"\n") else 0)
+
+
+def _declares_generated(data: bytes) -> bool:
+    head = b"\n".join(data.split(b"\n", _MARKER_HEAD_LINES)[:_MARKER_HEAD_LINES]).lower()
+    return any(marker in head for marker in _GENERATED_MARKERS)
+
+
+def _git(repo: Path, *args: str) -> bytes:
+    return subprocess.run(
+        ["git", "-C", str(repo), *args], check=True, capture_output=True,
+    ).stdout
+
+
+def _blob(repo: Path, rev: str, path: str) -> bytes:
+    return _git(repo, "show", f"{rev}:{path}")
+
+
+def _changed(repo: Path, base: str, head: str) -> list[tuple[str, str | None, str]]:
+    """(status letter, path at base or None, path at head) for each added or modified file."""
+    fields = _git(repo, "diff", "--name-status", "-z", "-M", f"{base}..{head}").split(b"\0")
+    rows: list[tuple[str, str | None, str]] = []
+    index = 0
+    while index < len(fields) and fields[index]:
+        status = fields[index].decode()[0]
+        if status == "R":
+            rows.append((status, fields[index + 1].decode(), fields[index + 2].decode()))
+            index += 3
+            continue
+        path = fields[index + 1].decode()
+        if status in "AM":
+            rows.append((status, path if status == "M" else None, path))
+        index += 2
+    return rows
+
+
+def _breach(before: int | None, after: int, threshold: int) -> str:
+    """Which way the diff breaks `threshold`, or '' when it does not."""
+    if after <= threshold:
+        return ""
+    if before is None:
+        return f"new file over {threshold}"
+    if before <= threshold:
+        return f"crossed {threshold}"
+    return f"grew a file over {threshold}" if after > before else ""
+
+
+def file_size_violations(repo: Path, base: str, head: str = "HEAD") -> list[FileSizeViolation]:
+    """Files the `base..head` diff leaves over a threshold, in diff order.
+
+    A new file over a threshold, an existing file the diff takes over it, and a file
+    already over it that the diff grows. A file already over it that the diff leaves the
+    same size or shrinks is not this stage's to split. A file that breaks the limit is
+    reported once, as blocking; one that breaks only the target is advisory.
+    """
+    violations: list[FileSizeViolation] = []
+    for _status, old_path, path in _changed(repo, base, head):
+        if not capped_path(path):
+            continue
+        data = _blob(repo, head, path)
+        after = physical_lines(data)
+        if after <= FILE_LINE_TARGET or _declares_generated(data):
+            continue
+        before = None if old_path is None else physical_lines(_blob(repo, base, old_path))
+        for threshold in (FILE_LINE_LIMIT, FILE_LINE_TARGET):
+            kind = _breach(before, after, threshold)
+            if kind:
+                violations.append(FileSizeViolation(path, before, after, kind, threshold))
+                break
+    return violations

package/runtime/python/okstra_ctl/initial_prompt_materialization.py

@@ -25,7 +25,6 @@ from .agent.invocation import (
     verify_agent_invocation,
 )
 from .path_hints import hydrate_active_run_context
-from .report_language import resolve_report_language
 from .report_inputs import report_narrative_path, uses_report_contract_v3
 from .report_synthesis_packet import (
     ReportSynthesisPacketError,
@@ -708,11 +707,9 @@ def _prompt_body(
             context.active_context,
             context.team_state,
             worker.model,
-            resolve_report_language(
-                context.project_root,
-                context.manifest,
-                context.active_context,
-            ),
+            # 조립이 `meta.reportLanguage` 로 옮기는 매니페스트 값. 설정을 다시 읽으면
+            # prepare 뒤의 설정 변경이 프롬프트와 리포트의 언어를 가른다.
+            str(context.manifest.get("reportLanguage") or "en"),
             synthesis_packet_path,
         )
     return analysis_prompt_body(

package/runtime/python/okstra_ctl/lead_progress.py

@@ -18,12 +18,14 @@ import argparse
 import json
 import sys
 from collections.abc import Mapping, Sequence
+from dataclasses import replace
 from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any
 
 from okstra_ctl.json_boundary import JsonBoundaryError, load_owned_object
-from okstra_ctl.lead_events import LeadEvent, append_lead_event
+from okstra_ctl.lead_events import LeadEvent, append_lead_event, read_lead_events
+from okstra_ctl.phases import catalog
 
 
 class ProgressRecordError(ValueError):
@@ -64,6 +66,11 @@ _DEFAULT_DETAIL: Mapping[str, str] = {
     "phase-7-teardown": "shutting-down-workers",
 }
 
+# phase 하나에 문구가 둘인 체크포인트. 고정 표만으로는 두 번째 호출이 첫 문구를
+# 다시 내므로, 원장과 task type 을 보고 고른다.
+_INTAKE_COMPLETE_DETAIL = "complete"
+_LEAD_ONLY_SYNTHESIS_DETAIL = "authoring final report"
+
 
 def _utc_now() -> str:
     return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
@@ -165,6 +172,39 @@ def _parse_field(raw: str) -> tuple[str, str]:
     return name.strip(), field_value.strip()
 
 
+def _intake_already_started(events_path: Path, event: LeadEvent) -> bool:
+    return any(
+        prior.event_type == "progress"
+        and prior.details.get("phase") == "phase-1-intake"
+        and (prior.task_key, prior.task_type, prior.run_seq)
+        == (event.task_key, event.task_type, event.run_seq)
+        for prior in read_lead_events(events_path)
+    )
+
+
+def _task_type_dispatches_report_writer(task_type: str) -> bool:
+    if task_type not in catalog.task_types():
+        return True
+    package = catalog.phase_record(task_type).package_name
+    profile = _read_json_object(
+        Path(catalog.__file__).parent / package / "profile.json", "phase profile"
+    )
+    return any(
+        isinstance(row, Mapping) and row.get("roleId") == "report-writer"
+        for row in profile.get("roles") or []
+    )
+
+
+def _default_detail(phase: str, events_path: Path, event: LeadEvent) -> str | None:
+    if phase == "phase-1-intake" and _intake_already_started(events_path, event):
+        return _INTAKE_COMPLETE_DETAIL
+    if phase == "phase-6-synthesis" and not _task_type_dispatches_report_writer(
+        event.task_type
+    ):
+        return _LEAD_ONLY_SYNTHESIS_DETAIL
+    return _DEFAULT_DETAIL.get(phase)
+
+
 def render_progress_line(
     phase: str,
     fields: Sequence[tuple[str, str]] = (),
@@ -199,7 +239,9 @@ def record_progress(
         )
         ordered.append(("worker", role))
     ordered.extend(fields)
-    line = render_progress_line(phase, ordered, detail)
+    events_path = _resolve_project_path(
+        project_root, _require_string(manifest, "leadEventsPath")
+    )
     event = LeadEvent(
         event_type="progress",
         lead_runtime=_require_string(manifest, "leadRuntime"),
@@ -207,15 +249,15 @@ def record_progress(
         task_type=_require_string(manifest, "taskType"),
         run_seq=_manifest_run_seq(manifest),
         timestamp=timestamp or _utc_now(),
-        details={
-            "phase": phase,
-            "line": line,
-            **({name: field_value for name, field_value in ordered}),
-        },
-    )
-    events_path = _resolve_project_path(
-        project_root, _require_string(manifest, "leadEventsPath")
     )
+    if detail is None:
+        detail = _default_detail(phase, events_path, event)
+    line = render_progress_line(phase, ordered, detail)
+    event = replace(event, details={
+        "phase": phase,
+        "line": line,
+        **({name: field_value for name, field_value in ordered}),
+    })
     append_lead_event(events_path, event)
     return event, warning
 
@@ -306,7 +348,10 @@ def _parser() -> argparse.ArgumentParser:
         help="extra `NAME=VALUE` token, in the order given")
     append_parser.add_argument(
         "--detail",
-        help="verb phrase after the fields; contract wording is the default")
+        help="verb phrase after the fields; contract wording is the default "
+             "(a second phase-1-intake renders `complete`, and phase-6-synthesis "
+             "in a task type without a report writer renders "
+             "`authoring final report`)")
     return parser
 
 

package/runtime/python/okstra_ctl/manager_cli.py

@@ -139,6 +139,11 @@ def _render_list(command: str, items: list[dict]) -> list[str]:
     return rows
 
 
+def _age_text(seconds: int) -> str:
+    hours, rest = divmod(int(seconds), 3600)
+    return f"{hours}h {rest // 60}m"
+
+
 def _render_manager_status(payload: dict) -> list[str]:
     rows: list[str] = []
     manifest = payload.get("manifest") if isinstance(payload.get("manifest"), dict) else {}
@@ -148,6 +153,10 @@ def _render_manager_status(payload: dict) -> list[str]:
     summary = payload.get("summary") if isinstance(payload.get("summary"), dict) else {}
     for key in ("planned", "missing", "running", "done", "blocked", "discussion"):
         rows.append(line(f"Summary {key}", summary.get(key)))
+    rows.append(line("Synced at", payload.get("syncedAt") or "never"))
+    if "syncAgeSeconds" in payload:
+        rows.append(line("Sync age", _age_text(payload["syncAgeSeconds"])))
+    rows.append(line("Changed since sync count", payload.get("changedSinceSyncCount", 0)))
     children = payload.get("children") if isinstance(payload.get("children"), list) else []
     for index, child in enumerate(children, 1):
         if not isinstance(child, dict):
@@ -156,7 +165,8 @@ def _render_manager_status(payload: dict) -> list[str]:
                            ("current phase", "currentPhase"), ("work status", "workStatus"),
                            ("summary", "summaryBucket"), ("project linked", "projectLinked"),
                            ("ticket", "ticketId"), ("brief path", "briefPath"),
-                           ("report path", "latestReportRecordPath"), ("error", "error")):
+                           ("report path", "latestReportRecordPath"),
+                           ("changed since sync", "changedSinceSync"), ("error", "error")):
             if key in child:
                 value = child.get(key)
                 rows.append(line(f"Child {index} {label}", ("yes" if value else "no") if isinstance(value, bool) else value))
@@ -332,6 +342,7 @@ def _parser() -> argparse.ArgumentParser:
     run.add_argument("--task-group", required=True)
     run.add_argument("--task-id", required=True)
     run.add_argument("--child-task-id", default=None)
+    run.add_argument("--allow-completed", action="store_true")
 
     split = task_sub.add_parser("split")
     split.add_argument("--manager-id", required=True)
@@ -466,6 +477,7 @@ def main(argv: list[str] | None = None) -> int:
                     args.task_id,
                     args.project_id,
                     child_task_id=args.child_task_id,
+                    allow_completed=args.allow_completed,
                 ),
                 args.json,
             )

package/runtime/python/okstra_ctl/manager_launch.py

@@ -20,7 +20,7 @@ from .manager_paths import (
     task_manifest_path,
 )
 from .manager_store import ManagerError, _now_iso, _read_json, _read_json_default, _write_json
-from .manager_sync import _resolve_task_root_read_only
+from .manager_sync import _snapshot_child, summary_bucket
 
 
 WORKER_DISPATCH_BACKEND = "subagent"
@@ -222,6 +222,25 @@ def _record_launch_prepared(
     )
 
 
+def _current_child_state(project_root: str, child: dict, target_task_key: str, *, allow_completed: bool) -> dict:
+    """대상 하위 task 를 마지막 sync 가 아니라 지금 프로젝트에서 다시 읽는다.
+
+    스냅샷은 sync 시점 값이라, 그 뒤 프로젝트에서 끝난 task 에 런치 패킷을 만들면 같은 일을 두 번 시킨다.
+    """
+    current = _snapshot_child(Path(project_root), {**child, "taskKey": target_task_key})
+    if current.get("error"):
+        raise ManagerError(f"{target_task_key}: cannot read child task state: {current['error']}")
+    if summary_bucket(current) == "done" and not allow_completed:
+        report = current.get("latestReportRecordPath") or ""
+        raise ManagerError(
+            f"{target_task_key}: already done in its project "
+            f"(last phase {current.get('lastCompletedPhase') or current.get('currentPhase') or 'unknown'}, "
+            f"report {Path(project_root) / report if report else 'none'}); nothing to launch. "
+            "Run `okstra manager task sync` to refresh the manager, or pass --allow-completed to prepare a launch anyway"
+        )
+    return current
+
+
 def build_launch_packet(
     home: Path,
     manager_id: str,
@@ -230,6 +249,7 @@ def build_launch_packet(
     project_id: str,
     *,
     child_task_id: str | None = None,
+    allow_completed: bool = False,
     now: str | None = None,
 ) -> dict:
     manifest = _read_json(task_manifest_path(home, manager_id, task_group, task_id))
@@ -244,6 +264,7 @@ def build_launch_packet(
     target_task_key = _target_task_key(project_id, task_group, child_task_id_value)
     _validate_child_task_key(child, target_task_key)
     project_root = _validated_project_root(project)
+    current = _current_child_state(project_root, child, target_task_key, allow_completed=allow_completed)
     created_at = now or _now_iso()
     brief_path = (Path(str(child["briefPath"])) if child.get("briefPath")
                   else _discussion_follow_up_brief(snapshot, target_task_key))
@@ -277,7 +298,7 @@ def build_launch_packet(
     # phase 를 채워야 하는데, 두 값이 다 주어지면 그 채우기를 건너뛴다(autofill_from_manifest).
     # 토론 후속 브리프는 권장 phase 를 따로 적지 않아도 requirements-discovery 에서 시작한다.
     recommended = child.get("recommendedPhase") or (DISCUSSION_FOLLOW_UP_PHASE if discussion_ref else "")
-    if recommended and _resolve_task_root_read_only(Path(project_root), target_task_key) is None:
+    if recommended and not current["exists"]:
         run_args.extend(["--task-type", str(recommended)])
     if brief_path is not None:
         run_args.extend(["--task-brief", str(brief_path)])

package/runtime/python/okstra_ctl/manager_sync.py

@@ -1,9 +1,11 @@
 """Read project-local okstra state into manager-owned snapshots."""
 from __future__ import annotations
 
+from datetime import datetime
 from pathlib import Path
 
 from okstra_project import TASKS_RELATIVE, StateError, parse_task_key, read_task_catalog, read_task_manifest, slugify
+from okstra_project.dirs import TASK_MANIFEST_FILENAME
 
 from . import next_phase
 from .next_phase import STATUS_BLOCKED, STATUS_TERMINAL
@@ -168,12 +170,35 @@ def summary_bucket(row: dict) -> str:
     return _POINTER_STATUS_BUCKETS.get(pointer_status, "running")
 
 
-def status_task(home: Path, manager_id: str, task_group: str, task_id: str) -> dict:
+def _epoch(value: str) -> int | None:
+    if not value:
+        return None
+    return int(datetime.fromisoformat(value.replace("Z", "+00:00")).timestamp())
+
+
+def _manifest_changed_since(project: dict | None, task_key: str, synced: int | None) -> bool:
+    """프로젝트의 task-manifest 가 마지막 sync 뒤에 바뀌었는지 — 파일 시각만 본다."""
+    if project is None or not task_key:
+        return False
+    root = Path(str(project.get("projectRoot") or ""))
+    if not root.is_dir():
+        return False
+    task_dir = _resolve_task_root_read_only(root, task_key)
+    manifest_path = task_dir / TASK_MANIFEST_FILENAME if task_dir is not None else None
+    if manifest_path is None or not manifest_path.is_file():
+        return False
+    # syncedAt 은 초 단위라 mtime 도 초로 내려 같은 초에 쓴 파일을 변경으로 세지 않는다.
+    return synced is None or int(manifest_path.stat().st_mtime) > synced
+
+
+def status_task(home: Path, manager_id: str, task_group: str, task_id: str, *, now: str | None = None) -> dict:
     manifest = _read_json(task_manifest_path(home, manager_id, task_group, task_id))
     children = _read_json_default(children_json_path(home, manager_id, task_group, task_id), {"children": []})
     snapshot = _read_json_default(snapshots_json_path(home, manager_id, task_group, task_id), {"children": []})
     by_key = {row.get("taskKey"): row for row in snapshot.get("children", []) if isinstance(row, dict)}
     linked = _project_map(home, manager_id)
+    synced_at = str(snapshot.get("syncedAt") or "")
+    synced = _epoch(synced_at)
     rows = []
     summary = {"planned": 0, "missing": 0, "running": 0, "done": 0, "blocked": 0, "discussion": 0}
     for child in children.get("children", []):
@@ -184,6 +209,17 @@ def status_task(home: Path, manager_id: str, task_group: str, task_id: str) -> d
         row["summaryBucket"] = "planned" if snapshot_row is None else summary_bucket(row)
         # `remove project` 는 하위 태스크를 남긴다. 등록 목록에 없으면 해제된 프로젝트의 것이다.
         row["projectLinked"] = str(child.get("projectId") or "") in linked
+        try:
+            row["changedSinceSync"] = _manifest_changed_since(
+                linked.get(str(child.get("projectId") or "")), str(child.get("taskKey") or ""), synced)
+        except StateError as exc:
+            row["changedSinceSync"] = True
+            row["error"] = str(exc)
         summary[row["summaryBucket"]] += 1
         rows.append(row)
-    return {"manifest": manifest, "summary": summary, "children": rows, "lastSnapshot": snapshot}
+    payload = {"manifest": manifest, "summary": summary, "children": rows, "lastSnapshot": snapshot,
+               "syncedAt": synced_at,
+               "changedSinceSyncCount": sum(1 for row in rows if row["changedSinceSync"])}
+    if synced is not None:
+        payload["syncAgeSeconds"] = max(0, (_epoch(now or _now_iso()) or 0) - synced)
+    return payload

package/runtime/python/okstra_ctl/mcp_cli.py

@@ -0,0 +1,179 @@
+"""`okstra mcp` — declare project MCP servers and check provider reachability."""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from okstra_project import resolve_project_root
+from okstra_project.resolver import ResolverError
+
+from .json_boundary import JsonBoundaryError
+from .mcp_servers import (
+    McpDeclarationError,
+    assess,
+    brief_source_warnings,
+    load_declarations,
+    parse_declaration,
+    probe_inventories,
+    provider_probes,
+    reachability_sentence,
+    remove_declaration,
+    upsert_declaration,
+)
+
+_CLI_EPILOG = r"""Usage:
+  okstra mcp list [--json] [--cwd <dir>]
+  okstra mcp add --name <name> --description <text> --tool <tool>... [--alias <name>...] [--notes <text>] [--cwd <dir>]
+  okstra mcp remove --name <name> [--cwd <dir>]
+  okstra mcp check [--provider <id>...] [--brief <path>] [--json] [--cwd <dir>]
+
+Declarations live in .okstra/project.json `mcpServers`. `--alias` names the
+server as a provider CLI lists it (for example `figma-desktop`). `check` runs
+each provider adapter's MCP listing command; it never sends an inference call.
+Add a missing server through that provider CLI's own MCP configuration.
+"""
+
+
+def _project_root(cwd: str) -> Path:
+    return resolve_project_root(cwd=str(Path(cwd).resolve()))
+
+
+def _list(root: Path, as_json: bool) -> int:
+    declarations, problems = load_declarations(root)
+    if as_json:
+        print(json.dumps({
+            "servers": [d.to_json() for d in declarations],
+            "problems": list(problems),
+        }, ensure_ascii=False, indent=2))
+        return 1 if problems else 0
+    if not declarations:
+        print("No MCP servers declared.")
+    for declaration in declarations:
+        aliases = f" (aliases: {', '.join(declaration.aliases)})" if declaration.aliases else ""
+        print(f"{declaration.name}{aliases}: {declaration.description}")
+        print(f"  tools: {', '.join(declaration.tools)}")
+        if declaration.notes:
+            print(f"  notes: {declaration.notes}")
+    for problem in problems:
+        print(f"invalid: {problem}")
+    return 1 if problems else 0
+
+
+def _add(root: Path, args: argparse.Namespace) -> int:
+    raw = {
+        "name": args.name,
+        "description": args.description,
+        "tools": args.tool or [],
+    }
+    if args.alias:
+        raw["aliases"] = args.alias
+    if args.notes:
+        raw["notes"] = args.notes
+    declaration, errors = parse_declaration(raw)
+    if declaration is None:
+        print("error: " + "; ".join(errors))
+        return 1
+    replaced = upsert_declaration(root, declaration)
+    print(f"{'Replaced' if replaced else 'Added'} MCP server `{declaration.name}`.")
+    print("Run `okstra mcp check` to see which providers can reach it.")
+    return 0
+
+
+def _remove(root: Path, name: str) -> int:
+    if not remove_declaration(root, name):
+        print(f"error: no MCP server named `{name}` is declared")
+        return 1
+    print(f"Removed MCP server `{name}`.")
+    return 0
+
+
+def _check(root: Path, providers: list[str], brief: str, as_json: bool) -> int:
+    from .registry.provider_registry import default_provider_registry
+
+    declarations, problems = load_declarations(root)
+    provider_ids = providers or list(default_provider_registry().ids())
+    rows = assess(declarations, probe_inventories(provider_probes(provider_ids), root))
+    brief_warnings = (
+        brief_source_warnings(Path(brief).read_text(encoding="utf-8"), declarations, rows)
+        if brief else ()
+    )
+    if as_json:
+        print(json.dumps({
+            "servers": [
+                {
+                    "name": row.server.name,
+                    "providers": [
+                        {
+                            "provider": cell.provider_id,
+                            "status": cell.status,
+                            "visibleName": cell.visible_name,
+                            "note": cell.note,
+                        }
+                        for cell in row.cells
+                    ],
+                }
+                for row in rows
+            ],
+            "problems": list(problems),
+            "briefWarnings": list(brief_warnings),
+        }, ensure_ascii=False, indent=2))
+        return 0
+    if not declarations:
+        print("No MCP servers declared. Register one with `okstra mcp add`.")
+    for row in rows:
+        print(f"{row.server.name}: {reachability_sentence(row)}")
+        for cell in row.cells:
+            if cell.note and cell.status != "missing":
+                print(f"  {cell.provider_id}: {cell.note}")
+    for problem in problems:
+        print(f"invalid: {problem}")
+    for warning in brief_warnings:
+        print(warning)
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        description="Declare project MCP servers and check provider reachability.",
+        epilog=_CLI_EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        prog="okstra mcp",
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+    listed = sub.add_parser("list")
+    listed.add_argument("--json", action="store_true")
+    listed.add_argument("--cwd", default=".")
+    add = sub.add_parser("add")
+    add.add_argument("--name", required=True)
+    add.add_argument("--description", required=True)
+    add.add_argument("--tool", action="append")
+    add.add_argument("--alias", action="append")
+    add.add_argument("--notes", default="")
+    add.add_argument("--cwd", default=".")
+    remove = sub.add_parser("remove")
+    remove.add_argument("--name", required=True)
+    remove.add_argument("--cwd", default=".")
+    check = sub.add_parser("check")
+    check.add_argument("--provider", action="append", default=[])
+    check.add_argument("--brief", default="")
+    check.add_argument("--json", action="store_true")
+    check.add_argument("--cwd", default=".")
+    args = parser.parse_args(argv)
+    try:
+        root = _project_root(args.cwd)
+        if args.command == "list":
+            return _list(root, args.json)
+        if args.command == "add":
+            return _add(root, args)
+        if args.command == "remove":
+            return _remove(root, args.name)
+        return _check(root, args.provider, args.brief, args.json)
+    except (McpDeclarationError, JsonBoundaryError, ResolverError, OSError, ValueError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())