xrefkit 0.4.3__tar.gz → 0.4.4__tar.gz

{xrefkit-0.4.3 → xrefkit-0.4.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xrefkit
-Version: 0.4.3
+Version: 0.4.4
 Summary: Portable XID, Skill, Knowledge, workflow, and MCP runtime for XRefKit
 Author: synthaicode
 License: MIT License
@@ -126,7 +126,36 @@ reason instead of inventing a criterion.
 
 ## Quick Start
 
-Install the package and initialize an instance:
+### Install from PyPI
+
+XRefKit requires Python 3.11 or later. For a normal installation, create a
+virtual environment and install the published package from PyPI:
+
+```powershell
+python -m venv .venv
+.\.venv\Scripts\Activate.ps1
+python -m pip install --upgrade pip
+python -m pip install xrefkit
+xrefkit init
+xrefkit --help
+```
+
+If the `xrefkit` command is not available on `PATH`, use the module form:
+
+```powershell
+python -m xrefkit --help
+```
+
+To use the integrated MCP server, install the optional MCP dependencies:
+
+```powershell
+python -m pip install "xrefkit[mcp]"
+xrefkit mcp serve --repo . --transport stdio
+```
+
+### Install from a checkout
+
+For XRefKit development, install the local checkout in editable mode instead:
 
 ```powershell
 python -m pip install -e .
@@ -140,6 +169,25 @@ Start the integrated MCP server over stdio:
 xrefkit mcp serve --repo . --transport stdio
 ```
 
+To import existing Skills and prepare a reviewable VS Code MCP setup, run:
+
+```powershell
+python -m pip install "xrefkit[mcp]"
+xrefkit mcp setup `
+  --repo C:\dev\itsm\XRefKit `
+  --import C:\work\existing-skills
+```
+
+The command writes `SETUP.md`, `import-report.json`, a VS Code
+`.vscode/mcp.json` example, and reviewed append text for `AGENTS.md` and
+`CLAUDE.md` into a temporary setup folder. Apply those artifacts after review:
+
+```powershell
+xrefkit mcp setup apply `
+  --source C:\Users\<user>\AppData\Local\Temp\xrefkit-setup-<id> `
+  --repo C:\dev\itsm\XRefKit
+```
+
 The server writes structured correlation events to
 `work/mcp/xid_audit.jsonl` by default. After `xrefkit skill run` returns a
 `run_id`, the client calls MCP `bind_skill_run` and executes the returned

{xrefkit-0.4.3 → xrefkit-0.4.4}/README.md

@@ -87,7 +87,36 @@ reason instead of inventing a criterion.
 
 ## Quick Start
 
-Install the package and initialize an instance:
+### Install from PyPI
+
+XRefKit requires Python 3.11 or later. For a normal installation, create a
+virtual environment and install the published package from PyPI:
+
+```powershell
+python -m venv .venv
+.\.venv\Scripts\Activate.ps1
+python -m pip install --upgrade pip
+python -m pip install xrefkit
+xrefkit init
+xrefkit --help
+```
+
+If the `xrefkit` command is not available on `PATH`, use the module form:
+
+```powershell
+python -m xrefkit --help
+```
+
+To use the integrated MCP server, install the optional MCP dependencies:
+
+```powershell
+python -m pip install "xrefkit[mcp]"
+xrefkit mcp serve --repo . --transport stdio
+```
+
+### Install from a checkout
+
+For XRefKit development, install the local checkout in editable mode instead:
 
 ```powershell
 python -m pip install -e .
@@ -101,6 +130,25 @@ Start the integrated MCP server over stdio:
 xrefkit mcp serve --repo . --transport stdio
 ```
 
+To import existing Skills and prepare a reviewable VS Code MCP setup, run:
+
+```powershell
+python -m pip install "xrefkit[mcp]"
+xrefkit mcp setup `
+  --repo C:\dev\itsm\XRefKit `
+  --import C:\work\existing-skills
+```
+
+The command writes `SETUP.md`, `import-report.json`, a VS Code
+`.vscode/mcp.json` example, and reviewed append text for `AGENTS.md` and
+`CLAUDE.md` into a temporary setup folder. Apply those artifacts after review:
+
+```powershell
+xrefkit mcp setup apply `
+  --source C:\Users\<user>\AppData\Local\Temp\xrefkit-setup-<id> `
+  --repo C:\dev\itsm\XRefKit
+```
+
 The server writes structured correlation events to
 `work/mcp/xid_audit.jsonl` by default. After `xrefkit skill run` returns a
 `run_id`, the client calls MCP `bind_skill_run` and executes the returned

{xrefkit-0.4.3 → xrefkit-0.4.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "xrefkit"
-version = "0.4.3"
+version = "0.4.4"
 description = "Portable XID, Skill, Knowledge, workflow, and MCP runtime for XRefKit"
 readme = "README.md"
 requires-python = ">=3.11"

xrefkit-0.4.4/tests/test_mcp_setup.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from xrefkit.__main__ import main
+
+
+def test_mcp_setup_writes_reviewable_workspace(tmp_path: Path, capsys) -> None:
+    output = tmp_path / "setup-output"
+    root = tmp_path / "repo"
+
+    assert main(["mcp", "setup", "--repo", str(root), "--output", str(output), "--json"]) == 0
+
+    payload = json.loads(capsys.readouterr().out)
+    assert payload["output"] == str(output.resolve())
+    assert (output / "SETUP.md").is_file()
+    assert (output / "vscode-mcp.json").is_file()
+    assert (output / "AGENTS.md.append.md").is_file()
+    assert (output / "CLAUDE.md.append.md").is_file()
+    assert (output / "import-report.json").is_file()
+
+    vscode = json.loads((output / "vscode-mcp.json").read_text(encoding="utf-8"))
+    server = vscode["servers"]["xrefkit"]
+    assert server["type"] == "stdio"
+    assert server["args"][-2:] == ["--transport", "stdio"]
+
+
+def test_mcp_setup_imports_existing_batch_skill_before_writing_report(tmp_path: Path, capsys) -> None:
+    source = tmp_path / "existing"
+    skill = source / "skills" / "legacy-review"
+    skill.mkdir(parents=True)
+    (skill / "SKILL.md").write_text("# Legacy Review\n\nReview the supplied change.\n", encoding="utf-8")
+    root = tmp_path / "repo"
+    output = tmp_path / "setup-output"
+
+    exit_code = main(
+        [
+            "mcp",
+            "setup",
+            "--repo",
+            str(root),
+            "--import",
+            str(source),
+            "--output",
+            str(output),
+            "--json",
+        ]
+    )
+    payload = json.loads(capsys.readouterr().out)
+    assert exit_code in {0, 1}
+    assert (root / "skills" / "imported.legacy-review" / "SKILL.md").is_file()
+    report = json.loads((output / "import-report.json").read_text(encoding="utf-8"))
+    assert report["import"]["converted_skills"][0]["skill_id"] == "imported.legacy-review"
+    assert payload["output"] == str(output.resolve())
+
+
+def test_mcp_setup_apply_copies_config_and_appends_instructions(tmp_path: Path, capsys) -> None:
+    output = tmp_path / "setup-output"
+    root = tmp_path / "repo"
+    root.mkdir()
+    assert main(["mcp", "setup", "--repo", str(root), "--output", str(output)]) == 0
+    capsys.readouterr()
+
+    assert main(["mcp", "setup-apply", "--source", str(output), "--repo", str(root)]) == 0
+    capsys.readouterr()
+    assert (root / ".vscode" / "mcp.json").is_file()
+    agents = (root / "AGENTS.md").read_text(encoding="utf-8")
+    assert "XRefKit MCP Skill Routing" in agents
+
+    assert main(["mcp", "setup-apply", "--source", str(output), "--repo", str(root)]) == 0
+    assert (root / "AGENTS.md").read_text(encoding="utf-8").count("XRefKit MCP Skill Routing") == 1

{xrefkit-0.4.3 → xrefkit-0.4.4}/xrefkit/__init__.py

@@ -2,4 +2,4 @@
 
 __all__ = ["__version__"]
 
-__version__ = "0.4.3"
+__version__ = "0.4.4"

{xrefkit-0.4.3 → xrefkit-0.4.4}/xrefkit/mcp/__init__.py

@@ -11,6 +11,16 @@ def main(argv: list[str] | None = None) -> int:
     from .server import main as server_main
 
     args = list(argv or [])
+    if args and args[0] == "setup":
+        from .setup import main as setup_main
+
+        if len(args) > 1 and args[1] == "apply":
+            return setup_main(["setup-apply", *args[2:]])
+        return setup_main(args)
+    if args and args[0] == "setup-apply":
+        from .setup import main as setup_main
+
+        return setup_main(args)
     if args and args[0] == "serve":
         args = args[1:]
     return server_main(args)

{xrefkit-0.4.3 → xrefkit-0.4.4}/xrefkit/mcp/bootstrap.py

@@ -37,6 +37,7 @@ import sys
 import urllib.request
 import zipfile
 from pathlib import Path
+from urllib.parse import urlsplit
 
 
 DIST_STATE_RELATIVE_PATH = ".xrefkit/dist-state.json"
@@ -50,6 +51,12 @@ class BootstrapError(RuntimeError):
     pass
 
 
+def _validate_http_url(url: str) -> None:
+    parsed = urlsplit(url)
+    if parsed.scheme not in {"http", "https"} or not parsed.netloc:
+        raise BootstrapError("bootstrap endpoints must use an absolute http(s) URL")
+
+
 def _ssl_context(ca_file: str | None) -> ssl.SSLContext:
     if ca_file:
         return ssl.create_default_context(cafile=ca_file)
@@ -57,8 +64,10 @@ def _ssl_context(ca_file: str | None) -> ssl.SSLContext:
 
 
 def http_get(url: str, ca_file: str | None = None, headers: dict[str, str] | None = None) -> bytes:
+    _validate_http_url(url)
     request = urllib.request.Request(url, headers=headers or {})
-    with urllib.request.urlopen(request, context=_ssl_context(ca_file)) as response:
+    # The URL scheme is validated above; B310 cannot infer that from Request.
+    with urllib.request.urlopen(request, context=_ssl_context(ca_file)) as response:  # nosec B310
         return response.read()
 
 
@@ -68,6 +77,7 @@ def http_post_json(
     ca_file: str | None = None,
     headers: dict[str, str] | None = None,
 ) -> tuple[bytes, dict[str, str]]:
+    _validate_http_url(url)
     request_headers = {
         "Content-Type": "application/json",
         "Accept": "application/json, text/event-stream",
@@ -79,7 +89,8 @@ def http_post_json(
         headers=request_headers,
         method="POST",
     )
-    with urllib.request.urlopen(request, context=_ssl_context(ca_file)) as response:
+    # The URL scheme is validated above; B310 cannot infer that from Request.
+    with urllib.request.urlopen(request, context=_ssl_context(ca_file)) as response:  # nosec B310
         return response.read(), {key.lower(): value for key, value in response.headers.items()}
 
 

xrefkit-0.4.4/xrefkit/mcp/setup.py

@@ -0,0 +1,234 @@
+"""Prepare an XRefKit repository and client configuration for MCP use."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import shutil
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+
+AGENT_APPEND = """## XRefKit MCP Skill Routing
+
+When the XRefKit MCP server is configured and available in this client, use
+its Skill catalog and semantic routing for Skill selection.
+
+The VS Code workspace MCP configuration is `.vscode/mcp.json`.
+
+Do not manually import or select individual Skill files during normal task
+execution. The administrator manages Skill registration; the client uses the
+MCP catalog to select and execute Skills.
+"""
+
+
+def _vscode_config(root: Path) -> dict[str, object]:
+    python_command = "python"
+    venv_python = root / ".venv" / "Scripts" / "python.exe"
+    if venv_python.is_file():
+        python_command = "${workspaceFolder}\\.venv\\Scripts\\python.exe"
+    return {
+        "servers": {
+            "xrefkit": {
+                "type": "stdio",
+                "command": python_command,
+                "args": [
+                    "-m",
+                    "xrefkit",
+                    "mcp",
+                    "serve",
+                    "--repo",
+                    "${workspaceFolder}",
+                    "--transport",
+                    "stdio",
+                ],
+            }
+        }
+    }
+
+
+def _run_xref_fix(root: Path) -> dict[str, object]:
+    proc = subprocess.run(
+        [sys.executable, "-m", "xrefkit", "xref", "fix", "--root", str(root), "--json"],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    try:
+        payload: object = json.loads(proc.stdout)
+    except json.JSONDecodeError:
+        payload = {"stdout": proc.stdout.strip(), "stderr": proc.stderr.strip()}
+    return {"returncode": proc.returncode, "result": payload}
+
+
+def _run_skill_checks(root: Path, metas: list[Path]) -> list[dict[str, object]]:
+    results: list[dict[str, object]] = []
+    for meta in metas:
+        proc = subprocess.run(
+            [
+                sys.executable,
+                "-m",
+                "xrefkit",
+                "skill",
+                "check",
+                "--root",
+                str(root),
+                "--meta",
+                str(meta),
+                "--level",
+                "trial",
+                "--json",
+            ],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+        try:
+            result: object = json.loads(proc.stdout)
+        except json.JSONDecodeError:
+            result = {"stdout": proc.stdout.strip(), "stderr": proc.stderr.strip()}
+        results.append({"meta": meta.relative_to(root).as_posix(), "returncode": proc.returncode, "result": result})
+    return results
+
+
+def _write_setup_files(
+    output: Path,
+    *,
+    root: Path,
+    import_report: dict[str, object] | None,
+    xref_report: dict[str, object],
+    checks: list[dict[str, object]],
+) -> None:
+    output.mkdir(parents=True, exist_ok=True)
+    (output / "vscode-mcp.json").write_text(
+        json.dumps(_vscode_config(root), ensure_ascii=False, indent=2) + "\n", encoding="utf-8"
+    )
+    (output / "AGENTS.md.append.md").write_text(AGENT_APPEND, encoding="utf-8")
+    (output / "CLAUDE.md.append.md").write_text(AGENT_APPEND, encoding="utf-8")
+    report = {"root": str(root), "import": import_report, "xref_fix": xref_report, "skill_checks": checks}
+    (output / "import-report.json").write_text(json.dumps(report, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+    guide = f"""# XRefKit MCP setup review
+
+Generated setup files:
+
+- `vscode-mcp.json`: copy to `{(root / '.vscode' / 'mcp.json').as_posix()}`.
+- `AGENTS.md.append.md`: review and append to `AGENTS.md`.
+- `CLAUDE.md.append.md`: review and append to `CLAUDE.md`.
+- `import-report.json`: import, XID fix, and Skill validation results.
+
+The setup command does not modify client instruction files or overwrite an
+existing VS Code MCP configuration. Apply these files only after review.
+
+After applying the files, open the repository in VS Code and start the
+`xrefkit` MCP server from the MCP controls.
+"""
+    (output / "SETUP.md").write_text(guide, encoding="utf-8")
+
+
+def setup(args: argparse.Namespace) -> int:
+    root = Path(args.repo).resolve()
+    root.mkdir(parents=True, exist_ok=True)
+    output = Path(args.output).resolve() if args.output else Path(tempfile.mkdtemp(prefix="xrefkit-setup-"))
+    import_report: dict[str, object] | None = None
+    metas: list[Path] = []
+
+    if args.import_source:
+        from xrefkit.import_skill import convert_skill, convert_skill_tree
+
+        source = Path(args.import_source).resolve()
+        if (source / "skills").is_dir() or args.batch:
+            result = convert_skill_tree(
+                source_root=source,
+                repo_root=root,
+                skill_id_prefix=args.skill_id_prefix,
+                target_skill_root=root / "skills",
+                dry_run=False,
+            )
+            import_report = result.to_dict()
+        else:
+            if not args.skill_id:
+                raise SystemExit("--skill-id is required when --import is a single Skill directory")
+            result = convert_skill(
+                source_dir=source,
+                source_root=source.parent,
+                repo_root=root,
+                skill_id=args.skill_id,
+                target_skill_dir=root / "skills" / args.skill_id,
+                dry_run=False,
+            )
+            import_report = result.to_dict()
+
+        if isinstance(import_report, dict):
+            metas = [root / Path(item["meta_doc"]) for item in import_report.get("converted_skills", []) if item.get("meta_doc")]
+            if not metas and import_report.get("meta_doc"):
+                metas = [root / Path(import_report["meta_doc"])]
+
+    xref_report = _run_xref_fix(root)
+    checks = _run_skill_checks(root, metas)
+    _write_setup_files(output, root=root, import_report=import_report, xref_report=xref_report, checks=checks)
+
+    payload = {"ok": xref_report["returncode"] == 0 and all(item["returncode"] == 0 for item in checks), "output": str(output), "report": str(output / "import-report.json")}
+    if args.json:
+        print(json.dumps(payload, ensure_ascii=False, indent=2))
+    else:
+        print(f"setup workspace: {output}")
+        print(f"guide: {output / 'SETUP.md'}")
+        print(f"report: {output / 'import-report.json'}")
+    return 0 if payload["ok"] else 1
+
+
+def apply_setup(args: argparse.Namespace) -> int:
+    source = Path(args.source).resolve()
+    root = Path(args.repo).resolve()
+    if not source.is_dir():
+        raise SystemExit(f"setup workspace does not exist: {source}")
+    destinations = {
+        source / "vscode-mcp.json": root / ".vscode" / "mcp.json",
+        source / "AGENTS.md.append.md": root / "AGENTS.md",
+        source / "CLAUDE.md.append.md": root / "CLAUDE.md",
+    }
+    for candidate, destination in destinations.items():
+        if not candidate.is_file():
+            raise SystemExit(f"missing setup artifact: {candidate}")
+        if destination.name == "mcp.json":
+            destination.parent.mkdir(parents=True, exist_ok=True)
+            if destination.exists() and destination.read_bytes() != candidate.read_bytes() and not args.force:
+                raise SystemExit(f"refusing to overwrite {destination}; use --force after review")
+            if not destination.exists() or destination.read_bytes() != candidate.read_bytes():
+                shutil.copyfile(candidate, destination)
+        else:
+            existing = destination.read_text(encoding="utf-8") if destination.exists() else ""
+            addition = candidate.read_text(encoding="utf-8")
+            if addition.strip() not in existing:
+                destination.write_text(existing.rstrip() + "\n\n" + addition, encoding="utf-8")
+    print(f"applied setup artifacts from: {source}")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="xrefkit mcp")
+    sub = parser.add_subparsers(dest="command", required=True)
+    setup_parser = sub.add_parser("setup", help="import Skills and generate reviewable MCP setup artifacts")
+    setup_parser.add_argument("--repo", required=True)
+    setup_parser.add_argument("--import", dest="import_source", default=None, help="Skill directory or batch root")
+    setup_parser.add_argument("--batch", action="store_true")
+    setup_parser.add_argument("--skill-id-prefix", default="imported")
+    setup_parser.add_argument("--skill-id", default=None)
+    setup_parser.add_argument("--output", default=None, help="Setup workspace; defaults to a temporary folder")
+    setup_parser.add_argument("--json", action="store_true")
+    setup_parser.set_defaults(handler=setup)
+
+    apply_parser = sub.add_parser("setup-apply", help="apply reviewed setup artifacts")
+    apply_parser.add_argument("--source", required=True)
+    apply_parser.add_argument("--repo", required=True)
+    apply_parser.add_argument("--force", action="store_true")
+    apply_parser.set_defaults(handler=apply_setup)
+
+    args = parser.parse_args(argv)
+    return args.handler(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

{xrefkit-0.4.3 → xrefkit-0.4.4}/xrefkit.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xrefkit
-Version: 0.4.3
+Version: 0.4.4
 Summary: Portable XID, Skill, Knowledge, workflow, and MCP runtime for XRefKit
 Author: synthaicode
 License: MIT License
@@ -126,7 +126,36 @@ reason instead of inventing a criterion.
 
 ## Quick Start
 
-Install the package and initialize an instance:
+### Install from PyPI
+
+XRefKit requires Python 3.11 or later. For a normal installation, create a
+virtual environment and install the published package from PyPI:
+
+```powershell
+python -m venv .venv
+.\.venv\Scripts\Activate.ps1
+python -m pip install --upgrade pip
+python -m pip install xrefkit
+xrefkit init
+xrefkit --help
+```
+
+If the `xrefkit` command is not available on `PATH`, use the module form:
+
+```powershell
+python -m xrefkit --help
+```
+
+To use the integrated MCP server, install the optional MCP dependencies:
+
+```powershell
+python -m pip install "xrefkit[mcp]"
+xrefkit mcp serve --repo . --transport stdio
+```
+
+### Install from a checkout
+
+For XRefKit development, install the local checkout in editable mode instead:
 
 ```powershell
 python -m pip install -e .
@@ -140,6 +169,25 @@ Start the integrated MCP server over stdio:
 xrefkit mcp serve --repo . --transport stdio
 ```
 
+To import existing Skills and prepare a reviewable VS Code MCP setup, run:
+
+```powershell
+python -m pip install "xrefkit[mcp]"
+xrefkit mcp setup `
+  --repo C:\dev\itsm\XRefKit `
+  --import C:\work\existing-skills
+```
+
+The command writes `SETUP.md`, `import-report.json`, a VS Code
+`.vscode/mcp.json` example, and reviewed append text for `AGENTS.md` and
+`CLAUDE.md` into a temporary setup folder. Apply those artifacts after review:
+
+```powershell
+xrefkit mcp setup apply `
+  --source C:\Users\<user>\AppData\Local\Temp\xrefkit-setup-<id> `
+  --repo C:\dev\itsm\XRefKit
+```
+
 The server writes structured correlation events to
 `work/mcp/xid_audit.jsonl` by default. After `xrefkit skill run` returns a
 `run_id`, the client calls MCP `bind_skill_run` and executes the returned

{xrefkit-0.4.3 → xrefkit-0.4.4}/xrefkit.egg-info/SOURCES.txt

@@ -21,6 +21,7 @@ tests/test_gate.py
 tests/test_goal_desired_state.py
 tests/test_instruction_workflow.py
 tests/test_knowledge_relations_validator.py
+tests/test_mcp_setup.py
 tests/test_ownership.py
 tests/test_packmeta.py
 tests/test_project_quality_baseline.py
@@ -84,6 +85,7 @@ xrefkit/mcp/ownership.py
 xrefkit/mcp/repository.py
 xrefkit/mcp/schemas.py
 xrefkit/mcp/server.py
+xrefkit/mcp/setup.py
 xrefkit/mcp/startup_contract_pack.py
 xrefkit/models/__init__.py
 xrefkit/models/common.py