witan-code 0.6.0__tar.gz → 0.8.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (86) hide show
  1. {witan_code-0.6.0 → witan_code-0.8.0}/CHANGELOG.md +66 -0
  2. witan_code-0.6.0/README.md → witan_code-0.8.0/PKG-INFO +92 -0
  3. witan_code-0.6.0/PKG-INFO → witan_code-0.8.0/README.md +60 -30
  4. {witan_code-0.6.0 → witan_code-0.8.0}/docs/CLI_REFERENCE.md +57 -0
  5. {witan_code-0.6.0 → witan_code-0.8.0}/pyproject.toml +20 -5
  6. witan_code-0.8.0/tests/test_cli_dispatch.py +248 -0
  7. {witan_code-0.6.0 → witan_code-0.8.0}/tests/test_cli_output_format.py +17 -13
  8. {witan_code-0.6.0 → witan_code-0.8.0}/tests/test_config_targets.py +66 -1
  9. {witan_code-0.6.0 → witan_code-0.8.0}/tests/test_context.py +13 -11
  10. witan_code-0.8.0/tests/test_remote_proxy.py +168 -0
  11. witan_code-0.8.0/tests/test_server.py +147 -0
  12. witan_code-0.8.0/tests/test_store.py +112 -0
  13. witan_code-0.8.0/tests/test_tasks.py +104 -0
  14. {witan_code-0.6.0 → witan_code-0.8.0}/tests/test_visualize.py +22 -0
  15. {witan_code-0.6.0 → witan_code-0.8.0}/witan_code/cli.py +247 -175
  16. {witan_code-0.6.0 → witan_code-0.8.0}/witan_code/config.py +51 -13
  17. {witan_code-0.6.0 → witan_code-0.8.0}/witan_code/context.py +8 -5
  18. {witan_code-0.6.0 → witan_code-0.8.0}/witan_code/elicit.py +6 -2
  19. {witan_code-0.6.0 → witan_code-0.8.0}/witan_code/queries/code_read.gq +14 -0
  20. witan_code-0.8.0/witan_code/remote/__init__.py +12 -0
  21. witan_code-0.8.0/witan_code/remote/oidc.py +80 -0
  22. witan_code-0.8.0/witan_code/remote/proxy.py +59 -0
  23. {witan_code-0.6.0 → witan_code-0.8.0}/witan_code/server.py +176 -11
  24. {witan_code-0.6.0 → witan_code-0.8.0}/witan_code/skills/witan-code/SKILL.md +10 -0
  25. {witan_code-0.6.0 → witan_code-0.8.0}/witan_code/store.py +86 -0
  26. {witan_code-0.6.0 → witan_code-0.8.0}/witan_code/visualize.py +38 -0
  27. witan_code-0.6.0/tests/test_server.py +0 -73
  28. {witan_code-0.6.0 → witan_code-0.8.0}/.gitignore +0 -0
  29. {witan_code-0.6.0 → witan_code-0.8.0}/config/claude.json +0 -0
  30. {witan_code-0.6.0 → witan_code-0.8.0}/config/copilot.json +0 -0
  31. {witan_code-0.6.0 → witan_code-0.8.0}/config/pi.json +0 -0
  32. {witan_code-0.6.0 → witan_code-0.8.0}/docs/BRANCH_INDEXING.md +0 -0
  33. {witan_code-0.6.0 → witan_code-0.8.0}/docs/EDGE_PRECISION_TIERS.md +0 -0
  34. {witan_code-0.6.0 → witan_code-0.8.0}/docs/PACKAGE_MAP.md +0 -0
  35. {witan_code-0.6.0 → witan_code-0.8.0}/docs/STAGE2_STITCHING.md +0 -0
  36. {witan_code-0.6.0 → witan_code-0.8.0}/docs/SYMBOL_FORMAT.md +0 -0
  37. {witan_code-0.6.0 → witan_code-0.8.0}/docs/SYMBOL_TABLE.md +0 -0
  38. {witan_code-0.6.0 → witan_code-0.8.0}/docs/USER_GUIDE.md +0 -0
  39. {witan_code-0.6.0 → witan_code-0.8.0}/install.sh +0 -0
  40. {witan_code-0.6.0 → witan_code-0.8.0}/tests/__init__.py +0 -0
  41. {witan_code-0.6.0 → witan_code-0.8.0}/tests/conftest.py +0 -0
  42. {witan_code-0.6.0 → witan_code-0.8.0}/tests/test_branches.py +0 -0
  43. {witan_code-0.6.0 → witan_code-0.8.0}/tests/test_bridge.py +0 -0
  44. {witan_code-0.6.0 → witan_code-0.8.0}/tests/test_cli_hooks.py +0 -0
  45. {witan_code-0.6.0 → witan_code-0.8.0}/tests/test_config.py +0 -0
  46. {witan_code-0.6.0 → witan_code-0.8.0}/tests/test_crossrepo.py +0 -0
  47. {witan_code-0.6.0 → witan_code-0.8.0}/tests/test_edges.py +0 -0
  48. {witan_code-0.6.0 → witan_code-0.8.0}/tests/test_elicit.py +0 -0
  49. {witan_code-0.6.0 → witan_code-0.8.0}/tests/test_enrichment.py +0 -0
  50. {witan_code-0.6.0 → witan_code-0.8.0}/tests/test_graph.py +0 -0
  51. {witan_code-0.6.0 → witan_code-0.8.0}/tests/test_hooks.py +0 -0
  52. {witan_code-0.6.0 → witan_code-0.8.0}/tests/test_indexer.py +0 -0
  53. {witan_code-0.6.0 → witan_code-0.8.0}/tests/test_languages.py +0 -0
  54. {witan_code-0.6.0 → witan_code-0.8.0}/tests/test_maintenance.py +0 -0
  55. {witan_code-0.6.0 → witan_code-0.8.0}/tests/test_package_map.py +0 -0
  56. {witan_code-0.6.0 → witan_code-0.8.0}/tests/test_repo.py +0 -0
  57. {witan_code-0.6.0 → witan_code-0.8.0}/tests/test_setup.py +0 -0
  58. {witan_code-0.6.0 → witan_code-0.8.0}/tests/test_stitch.py +0 -0
  59. {witan_code-0.6.0 → witan_code-0.8.0}/tests/test_symbol_table.py +0 -0
  60. {witan_code-0.6.0 → witan_code-0.8.0}/uv.lock +0 -0
  61. {witan_code-0.6.0 → witan_code-0.8.0}/witan_code/__init__.py +0 -0
  62. {witan_code-0.6.0 → witan_code-0.8.0}/witan_code/__main__.py +0 -0
  63. {witan_code-0.6.0 → witan_code-0.8.0}/witan_code/bridge.py +0 -0
  64. {witan_code-0.6.0 → witan_code-0.8.0}/witan_code/bridge_extractors.py +0 -0
  65. {witan_code-0.6.0 → witan_code-0.8.0}/witan_code/edges.py +0 -0
  66. {witan_code-0.6.0 → witan_code-0.8.0}/witan_code/extensions/pi/codegraph.ts +0 -0
  67. {witan_code-0.6.0 → witan_code-0.8.0}/witan_code/graph.py +0 -0
  68. {witan_code-0.6.0 → witan_code-0.8.0}/witan_code/hooks.py +0 -0
  69. {witan_code-0.6.0 → witan_code-0.8.0}/witan_code/indexer.py +0 -0
  70. {witan_code-0.6.0 → witan_code-0.8.0}/witan_code/maintenance.py +0 -0
  71. {witan_code-0.6.0 → witan_code-0.8.0}/witan_code/output.py +0 -0
  72. {witan_code-0.6.0 → witan_code-0.8.0}/witan_code/package_map.py +0 -0
  73. {witan_code-0.6.0 → witan_code-0.8.0}/witan_code/queries/bridge.gq +0 -0
  74. {witan_code-0.6.0 → witan_code-0.8.0}/witan_code/queries/code_mutations.gq +0 -0
  75. {witan_code-0.6.0 → witan_code-0.8.0}/witan_code/queries/delete.gq +0 -0
  76. {witan_code-0.6.0 → witan_code-0.8.0}/witan_code/queries_ts/bash.scm +0 -0
  77. {witan_code-0.6.0 → witan_code-0.8.0}/witan_code/queries_ts/hcl.scm +0 -0
  78. {witan_code-0.6.0 → witan_code-0.8.0}/witan_code/queries_ts/python.scm +0 -0
  79. {witan_code-0.6.0 → witan_code-0.8.0}/witan_code/queries_ts/sql.scm +0 -0
  80. {witan_code-0.6.0 → witan_code-0.8.0}/witan_code/queries_ts/typescript.scm +0 -0
  81. {witan_code-0.6.0 → witan_code-0.8.0}/witan_code/queries_ts/yaml.scm +0 -0
  82. {witan_code-0.6.0 → witan_code-0.8.0}/witan_code/repo.py +0 -0
  83. {witan_code-0.6.0 → witan_code-0.8.0}/witan_code/schema/bridge-schema.pg +0 -0
  84. {witan_code-0.6.0 → witan_code-0.8.0}/witan_code/schema/code-schema.pg +0 -0
  85. {witan_code-0.6.0 → witan_code-0.8.0}/witan_code/setup.py +0 -0
  86. {witan_code-0.6.0 → witan_code-0.8.0}/witan_code/stitch.py +0 -0
@@ -6,6 +6,72 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
6
6
  and this project adheres to [Semantic Versioning](https://semver.org/) (pre-1.0:
7
7
  a MINOR bump may include breaking changes).
8
8
 
9
+ ## [0.8.0] - 2026-07-31
10
+
11
+ ### Added
12
+
13
+ - **Remote MCP-client mode for the CLI (ADR-0005 parity).** With
14
+ `WITAN_REMOTE_URL` + `WITAN_OIDC_ISSUER` set (or `remote_url`/`oidc_*` on the
15
+ matched `[targets.<name>]` block), the read commands — `symbols`, `deps`,
16
+ `stitch`, `repos`, `branches` — dispatch over `streamable-http` to a deployed
17
+ witan service instead of this machine's stores, authenticated with a per-user
18
+ Keycloak JWT. Previously only witan-council's CLI could reach a deployment,
19
+ even though `witan serve` has always mounted this server's `code_*` tools onto
20
+ the same endpoint. Indexing and store maintenance stay local unconditionally:
21
+ they need the checkout and the store files on disk.
22
+ - **`witan-code login` / `logout` / `whoami`** — the OIDC device grant against
23
+ the configured deployment. The token cache and default client id are shared
24
+ with the `witan` CLI and keyed by `(issuer, client id)`, so a prior
25
+ `witan login` already covers witan-code and vice versa.
26
+ - **Four MCP tools** backing the commands above, so both the CLI and an agent
27
+ reach the same data: `code_repo_symbols` (a repo's contract surface — what it
28
+ exports, what it expects), `code_repo_dependencies` (the whole "repo A depends
29
+ on repo B" graph), `code_indexed_repos` and `code_indexed_branches` (coverage:
30
+ which repos and branch views exist, and how fresh).
31
+
32
+ ### Changed
33
+
34
+ - **The read commands route through the tool surface, not `OmnigraphClient`.**
35
+ The CLI and the MCP server used to be two disconnected implementations of the
36
+ same queries; the commands now dispatch through a `_srv()` indirection that is
37
+ the in-process server module locally and an MCP proxy remotely. Output is
38
+ unchanged in local mode.
39
+ - **Requires `witan-core>=0.6`** and pulls its `remote` extra — the shared
40
+ `RemoteConfig` and OIDC client stack live there. No new transitive weight:
41
+ `fastmcp` was already required and itself depends on `httpx2`.
42
+ - `witan-code branches --prune` refuses to run in remote mode (it deletes from
43
+ the local stores, comparing against this machine's git refs). Listing works
44
+ against a deployment.
45
+
46
+ ## [0.7.0] - 2026-07-30
47
+
48
+ ### Changed
49
+
50
+ - **Requires `witan-core>=0.5`** (was `>=0.2`) — the server now imports
51
+ `witan_core.caching` and `elicit.MRTRElicitationMiddleware`, neither of which
52
+ exists below that.
53
+ - **`code_reindex` is now async and no longer blocks the event loop.** It was a
54
+ plain `def`, so a multi-minute index stalled every other request on the server
55
+ for its whole run; the indexer now runs on a thread.
56
+ - **`tools/list` declares a cache directive** — `ttlMs=300000`,
57
+ `cacheScope=private`.
58
+ - **Elicitation works on the stateless protocol era again** — the index-now
59
+ confirms and the repo prompt had been silently returning their
60
+ non-interactive defaults on any MCP 2026-07-28 connection. See the
61
+ `witan-core` 0.5.0 entry.
62
+
63
+ ### Added
64
+
65
+ - **`code_reindex` accepts task-augmented execution** (`io.modelcontextprotocol/tasks`,
66
+ SEP-2663) via the new optional `witan-code[tasks]` extra: a client can take a
67
+ handle and poll rather than holding the tool call open for the whole rebuild.
68
+ Opt-in per call — a client that does not ask gets the same completed result as
69
+ before. Without the extra the tool stays synchronous; the extra is separate
70
+ because it pulls a Docket/Redis stack most installs never need, and because it
71
+ requires FastMCP 4 while this package still supports 3.4.x. Note that while
72
+ 4.0 is still a pre-release, `witan-code[tasks]` needs `--prerelease=allow`
73
+ under uv; the base package does not.
74
+
9
75
  ## [0.6.0] - 2026-07-21
10
76
 
11
77
  ### Fixed
@@ -1,3 +1,35 @@
1
+ Metadata-Version: 2.4
2
+ Name: witan-code
3
+ Version: 0.8.0
4
+ Summary: witan-code — tree-sitter code graph + cross-repo bridge (mounts under `witan code`)
5
+ Project-URL: Homepage, https://github.com/mitodl/agent-kit/tree/main/mcp/servers/witan-code
6
+ Project-URL: Repository, https://github.com/mitodl/agent-kit
7
+ Project-URL: Documentation, https://github.com/mitodl/agent-kit/blob/main/mcp/servers/witan-code/README.md
8
+ Project-URL: Issues, https://github.com/mitodl/agent-kit/issues
9
+ License-Expression: BSD-3-Clause
10
+ Keywords: agent,code-graph,coding-agent,mcp,static-analysis,tree-sitter
11
+ Classifier: Programming Language :: Python :: 3
12
+ Requires-Python: >=3.11
13
+ Requires-Dist: agent-config-kit<1,>=0.4
14
+ Requires-Dist: cyclopts<5,>=4
15
+ Requires-Dist: fastmcp<5,>=3.4.2
16
+ Requires-Dist: pydantic<3,>=2
17
+ Requires-Dist: pyyaml<7,>=6
18
+ Requires-Dist: rich>=13
19
+ Requires-Dist: tomli-w<2,>=1
20
+ Requires-Dist: tree-sitter-bash<0.26,>=0.25
21
+ Requires-Dist: tree-sitter-go<0.26,>=0.25
22
+ Requires-Dist: tree-sitter-hcl<1.3,>=1.2
23
+ Requires-Dist: tree-sitter-python<0.26,>=0.25
24
+ Requires-Dist: tree-sitter-sql<0.4,>=0.3
25
+ Requires-Dist: tree-sitter-typescript<0.24,>=0.23
26
+ Requires-Dist: tree-sitter-yaml<0.8,>=0.7
27
+ Requires-Dist: tree-sitter<0.26,>=0.25
28
+ Requires-Dist: witan-core[cli,remote]<1,>=0.6
29
+ Provides-Extra: tasks
30
+ Requires-Dist: fastmcp-tasks<5,>=4.0.0b1; extra == 'tasks'
31
+ Description-Content-Type: text/markdown
32
+
1
33
  # witan-code
2
34
 
3
35
  > "witan" is pronounced `WIT-ən` (/ˈwɪtən/) — rhymes with "written" minus the r.
@@ -307,6 +339,11 @@ symlink alternative:
307
339
  | `WITAN_CODE_OPTIMIZE_INTERVAL` | `86400` (daily) | throttle window (seconds) for `checkpoint`'s opportunistic store compaction; `0` disables it |
308
340
  | `WITAN_CONFIG` | `~/.config/witan/config.toml` | config file path (see below) |
309
341
  | `WITAN_TARGET` | — | force a named `[targets.<name>]` block instead of auto-detecting one |
342
+ | `WITAN_REMOTE_URL` | — | a deployed witan MCP endpoint; routes the read commands through it (see [Remote mode](#remote-mode)) |
343
+ | `WITAN_OIDC_ISSUER` | — | Keycloak realm `witan-code login` authenticates against. Required whenever `WITAN_REMOTE_URL` is set |
344
+ | `WITAN_OIDC_CLIENT_ID` | `witan-cli` | public OIDC client id for the device grant. Shared with witan on purpose — see [Remote mode](#remote-mode) |
345
+ | `WITAN_OIDC_AUDIENCE` | — | audience/resource to request, matching the deployment's expected `aud` claim |
346
+ | `WITAN_TOKEN_CACHE` | `~/.config/witan/tokens.json` | where the 0600 token cache lives (shared with witan) |
310
347
 
311
348
  The store URI for a repo is `<dir>/<sanitized-slug>.omni`, where the slug's `/`
312
349
  and `:` are replaced with `_`. The shared cross-repo bridge lives alongside them
@@ -330,6 +367,12 @@ the same name — each server reads only the fields it knows:
330
367
  server = "http://witan.internal:8080" # witan (witan-council)
331
368
  code_dir = "/mnt/work/witan-code" # witan-code
332
369
  match_orgs = ["myorg"]
370
+
371
+ [targets.hosted]
372
+ # remote_url/oidc_* route BOTH CLIs at one deployed endpoint — see Remote mode.
373
+ remote_url = "https://witan.example.org/mcp"
374
+ oidc_issuer = "https://sso.example.org/realms/ol-platform-engineering"
375
+ match_orgs = ["ol-platform-engineering"]
333
376
  ```
334
377
 
335
378
  Environment variables always win over `config.toml`.
@@ -362,6 +405,18 @@ that repo's bridge branch overlay instead of `main` — see
362
405
  | `code_interface_consumers(kind, key)` | repos that **consume** it (`endpoint` keys are normalized from raw paths) |
363
406
  | `code_cross_repo_impact(symbol_id)` | the symbol's own bindings + every binding for those same contracts in **other** repos |
364
407
  | `code_interface_search(query, kind=None)` | BM25 search over interface bindings by normalized key |
408
+ | `code_precise_edges(repo=None)` | Stage-2 cross-repo edges resolved by canonical symbol string |
409
+ | `code_unresolved_symbols(repo=None)` | external references with no precise match (indexing-coverage gaps) |
410
+ | `code_repo_symbols(repo=None, role=None, scheme=None)` | a repo's symbol table — what it exports, what it expects |
411
+ | `code_repo_dependencies(kind=None, repo=None)` | the whole "repo A depends on repo B" graph (`{repos, edges}`) |
412
+
413
+ Coverage tools (which stores exist at all — read the store directory, not the
414
+ graph):
415
+
416
+ | Tool | Returns |
417
+ |------|---------|
418
+ | `code_indexed_repos()` | every indexed repo with file count, size, and last-indexed timestamp |
419
+ | `code_indexed_branches()` | the omnigraph branches each repo's store carries |
365
420
 
366
421
  ## CLI
367
422
 
@@ -405,10 +460,47 @@ that repo's bridge branch overlay instead of `main` — see
405
460
  - `checkpoint` — opportunistically compact the current repo's store and the
406
461
  bridge store if due (see [Hooks](#hooks)); registered as the `Stop` hook,
407
462
  not usually run by hand.
463
+ - `login` / `logout` / `whoami` — authenticate to a deployed witan service
464
+ (see [Remote mode](#remote-mode)); no-ops with nothing configured.
408
465
 
409
466
  Both print a summary: files scanned/indexed/skipped, symbols, edges, errors. A
410
467
  parse failure on one file logs to stderr and continues.
411
468
 
469
+ ## Remote mode
470
+
471
+ The deployed witan service mounts this server's `code_*` tools into its own
472
+ FastMCP server with no prefix (`witan serve`), so one endpoint serves both tool
473
+ surfaces. Point the CLI at it and the **read** commands query the deployment's
474
+ code graphs instead of this machine's stores — witan-council's ADR-0005 path a,
475
+ same mechanism ([`docs/adr/0005`](../witan/docs/adr/0005-secure-cli-path-into-deployed-witan.md)):
476
+
477
+ ```bash
478
+ export WITAN_REMOTE_URL=https://witan.example.org/mcp
479
+ export WITAN_OIDC_ISSUER=https://sso.example.org/realms/ol-platform-engineering
480
+ witan-code login # OIDC device grant; approve in a browser
481
+ witan-code repos # now answers about the deployment's stores
482
+ ```
483
+
484
+ Or put `remote_url`/`oidc_issuer`/`oidc_client_id`/`oidc_audience` on a
485
+ `[targets.<name>]` block, alongside that target's `code_dir` — the same four
486
+ keys witan reads, so one block routes both CLIs.
487
+
488
+ Which commands move:
489
+
490
+ | Local **and** remote | Local only |
491
+ |---|---|
492
+ | `symbols`, `deps`, `stitch`, `repos`, `branches` | `index`, `reindex`, `optimize`, `cleanup`, `checkpoint`, `branches --prune`, the four hooks |
493
+
494
+ Indexing and store maintenance need the git checkout and the store files on
495
+ disk, so they always run against this machine and ignore `WITAN_REMOTE_URL`
496
+ entirely.
497
+
498
+ The token cache (`~/.config/witan/tokens.json`) and the default client id
499
+ (`witan-cli`) are shared with the `witan` CLI, and cache entries are keyed by
500
+ `(issuer, client id)` — so **one login covers both**. If you have already run
501
+ `witan login` against the same deployment, `witan-code login` is unnecessary;
502
+ conversely `witan-code logout` also logs `witan` out.
503
+
412
504
  ## Store compaction
413
505
 
414
506
  Every `load()`/`mutate()` call (indexing) appends a new tiny Lance fragment +
@@ -1,33 +1,3 @@
1
- Metadata-Version: 2.4
2
- Name: witan-code
3
- Version: 0.6.0
4
- Summary: witan-code — tree-sitter code graph + cross-repo bridge (mounts under `witan code`)
5
- Project-URL: Homepage, https://github.com/mitodl/agent-kit/tree/main/mcp/servers/witan-code
6
- Project-URL: Repository, https://github.com/mitodl/agent-kit
7
- Project-URL: Documentation, https://github.com/mitodl/agent-kit/blob/main/mcp/servers/witan-code/README.md
8
- Project-URL: Issues, https://github.com/mitodl/agent-kit/issues
9
- License-Expression: BSD-3-Clause
10
- Keywords: agent,code-graph,coding-agent,mcp,static-analysis,tree-sitter
11
- Classifier: Programming Language :: Python :: 3
12
- Requires-Python: >=3.11
13
- Requires-Dist: agent-config-kit<1,>=0.4
14
- Requires-Dist: cyclopts<5,>=4
15
- Requires-Dist: fastmcp<4,>=3.4.2
16
- Requires-Dist: pydantic<3,>=2
17
- Requires-Dist: pyyaml<7,>=6
18
- Requires-Dist: rich>=13
19
- Requires-Dist: tomli-w<2,>=1
20
- Requires-Dist: tree-sitter-bash<0.26,>=0.25
21
- Requires-Dist: tree-sitter-go<0.26,>=0.25
22
- Requires-Dist: tree-sitter-hcl<1.3,>=1.2
23
- Requires-Dist: tree-sitter-python<0.26,>=0.25
24
- Requires-Dist: tree-sitter-sql<0.4,>=0.3
25
- Requires-Dist: tree-sitter-typescript<0.24,>=0.23
26
- Requires-Dist: tree-sitter-yaml<0.8,>=0.7
27
- Requires-Dist: tree-sitter<0.26,>=0.25
28
- Requires-Dist: witan-core[cli]<1,>=0.2
29
- Description-Content-Type: text/markdown
30
-
31
1
  # witan-code
32
2
 
33
3
  > "witan" is pronounced `WIT-ən` (/ˈwɪtən/) — rhymes with "written" minus the r.
@@ -337,6 +307,11 @@ symlink alternative:
337
307
  | `WITAN_CODE_OPTIMIZE_INTERVAL` | `86400` (daily) | throttle window (seconds) for `checkpoint`'s opportunistic store compaction; `0` disables it |
338
308
  | `WITAN_CONFIG` | `~/.config/witan/config.toml` | config file path (see below) |
339
309
  | `WITAN_TARGET` | — | force a named `[targets.<name>]` block instead of auto-detecting one |
310
+ | `WITAN_REMOTE_URL` | — | a deployed witan MCP endpoint; routes the read commands through it (see [Remote mode](#remote-mode)) |
311
+ | `WITAN_OIDC_ISSUER` | — | Keycloak realm `witan-code login` authenticates against. Required whenever `WITAN_REMOTE_URL` is set |
312
+ | `WITAN_OIDC_CLIENT_ID` | `witan-cli` | public OIDC client id for the device grant. Shared with witan on purpose — see [Remote mode](#remote-mode) |
313
+ | `WITAN_OIDC_AUDIENCE` | — | audience/resource to request, matching the deployment's expected `aud` claim |
314
+ | `WITAN_TOKEN_CACHE` | `~/.config/witan/tokens.json` | where the 0600 token cache lives (shared with witan) |
340
315
 
341
316
  The store URI for a repo is `<dir>/<sanitized-slug>.omni`, where the slug's `/`
342
317
  and `:` are replaced with `_`. The shared cross-repo bridge lives alongside them
@@ -360,6 +335,12 @@ the same name — each server reads only the fields it knows:
360
335
  server = "http://witan.internal:8080" # witan (witan-council)
361
336
  code_dir = "/mnt/work/witan-code" # witan-code
362
337
  match_orgs = ["myorg"]
338
+
339
+ [targets.hosted]
340
+ # remote_url/oidc_* route BOTH CLIs at one deployed endpoint — see Remote mode.
341
+ remote_url = "https://witan.example.org/mcp"
342
+ oidc_issuer = "https://sso.example.org/realms/ol-platform-engineering"
343
+ match_orgs = ["ol-platform-engineering"]
363
344
  ```
364
345
 
365
346
  Environment variables always win over `config.toml`.
@@ -392,6 +373,18 @@ that repo's bridge branch overlay instead of `main` — see
392
373
  | `code_interface_consumers(kind, key)` | repos that **consume** it (`endpoint` keys are normalized from raw paths) |
393
374
  | `code_cross_repo_impact(symbol_id)` | the symbol's own bindings + every binding for those same contracts in **other** repos |
394
375
  | `code_interface_search(query, kind=None)` | BM25 search over interface bindings by normalized key |
376
+ | `code_precise_edges(repo=None)` | Stage-2 cross-repo edges resolved by canonical symbol string |
377
+ | `code_unresolved_symbols(repo=None)` | external references with no precise match (indexing-coverage gaps) |
378
+ | `code_repo_symbols(repo=None, role=None, scheme=None)` | a repo's symbol table — what it exports, what it expects |
379
+ | `code_repo_dependencies(kind=None, repo=None)` | the whole "repo A depends on repo B" graph (`{repos, edges}`) |
380
+
381
+ Coverage tools (which stores exist at all — read the store directory, not the
382
+ graph):
383
+
384
+ | Tool | Returns |
385
+ |------|---------|
386
+ | `code_indexed_repos()` | every indexed repo with file count, size, and last-indexed timestamp |
387
+ | `code_indexed_branches()` | the omnigraph branches each repo's store carries |
395
388
 
396
389
  ## CLI
397
390
 
@@ -435,10 +428,47 @@ that repo's bridge branch overlay instead of `main` — see
435
428
  - `checkpoint` — opportunistically compact the current repo's store and the
436
429
  bridge store if due (see [Hooks](#hooks)); registered as the `Stop` hook,
437
430
  not usually run by hand.
431
+ - `login` / `logout` / `whoami` — authenticate to a deployed witan service
432
+ (see [Remote mode](#remote-mode)); no-ops with nothing configured.
438
433
 
439
434
  Both print a summary: files scanned/indexed/skipped, symbols, edges, errors. A
440
435
  parse failure on one file logs to stderr and continues.
441
436
 
437
+ ## Remote mode
438
+
439
+ The deployed witan service mounts this server's `code_*` tools into its own
440
+ FastMCP server with no prefix (`witan serve`), so one endpoint serves both tool
441
+ surfaces. Point the CLI at it and the **read** commands query the deployment's
442
+ code graphs instead of this machine's stores — witan-council's ADR-0005 path a,
443
+ same mechanism ([`docs/adr/0005`](../witan/docs/adr/0005-secure-cli-path-into-deployed-witan.md)):
444
+
445
+ ```bash
446
+ export WITAN_REMOTE_URL=https://witan.example.org/mcp
447
+ export WITAN_OIDC_ISSUER=https://sso.example.org/realms/ol-platform-engineering
448
+ witan-code login # OIDC device grant; approve in a browser
449
+ witan-code repos # now answers about the deployment's stores
450
+ ```
451
+
452
+ Or put `remote_url`/`oidc_issuer`/`oidc_client_id`/`oidc_audience` on a
453
+ `[targets.<name>]` block, alongside that target's `code_dir` — the same four
454
+ keys witan reads, so one block routes both CLIs.
455
+
456
+ Which commands move:
457
+
458
+ | Local **and** remote | Local only |
459
+ |---|---|
460
+ | `symbols`, `deps`, `stitch`, `repos`, `branches` | `index`, `reindex`, `optimize`, `cleanup`, `checkpoint`, `branches --prune`, the four hooks |
461
+
462
+ Indexing and store maintenance need the git checkout and the store files on
463
+ disk, so they always run against this machine and ignore `WITAN_REMOTE_URL`
464
+ entirely.
465
+
466
+ The token cache (`~/.config/witan/tokens.json`) and the default client id
467
+ (`witan-cli`) are shared with the `witan` CLI, and cache entries are keyed by
468
+ `(issuer, client id)` — so **one login covers both**. If you have already run
469
+ `witan login` against the same deployment, `witan-code login` is unnecessary;
470
+ conversely `witan-code logout` also logs `witan` out.
471
+
442
472
  ## Store compaction
443
473
 
444
474
  Every `load()`/`mutate()` call (indexing) appends a new tiny Lance fragment +
@@ -18,6 +18,18 @@ mounted under the umbrella CLI, e.g. `witan --output-format json code repos`.
18
18
  Boolean flags follow cyclopts' `--flag`/`--no-flag` convention; both forms are
19
19
  always available even where only `--flag` is shown below.
20
20
 
21
+ ## Local vs. remote
22
+
23
+ The read commands — `symbols`, `deps`, `stitch`, `repos`, `branches` — dispatch
24
+ through the same `code_*` tool surface the MCP server exposes, so setting
25
+ `WITAN_REMOTE_URL` (plus `WITAN_OIDC_ISSUER`) points them at a deployed witan
26
+ service instead of this machine's stores. See
27
+ [Remote mode](../README.md#remote-mode) and `login`/`logout`/`whoami` below.
28
+
29
+ Everything else operates on the checkout and the store files on disk — `index`,
30
+ `reindex`, `optimize`, `cleanup`, `checkpoint`, `branches --prune`, and the
31
+ hook commands — and always runs locally regardless of `WITAN_REMOTE_URL`.
32
+
21
33
  ## `index [PATH]`
22
34
 
23
35
  Incrementally index `PATH` (file or directory). Files whose content hash is
@@ -157,3 +169,48 @@ re-running after an omnigraph version bump refreshes the binary.
157
169
  witan-code setup
158
170
  witan-code setup --dry-run
159
171
  ```
172
+
173
+ ## `login`
174
+
175
+ Authenticate to the deployed witan service named by `WITAN_REMOTE_URL` +
176
+ `WITAN_OIDC_ISSUER` (or the matched `[targets.<name>]` block) via the OIDC
177
+ device-authorization grant. Prints a verification URL and a user code; approve
178
+ it in a browser and the resulting token is cached at
179
+ `~/.config/witan/tokens.json` (mode 0600) and refreshed automatically.
180
+
181
+ Exits 1 with an explanation when no remote is configured.
182
+
183
+ No parameters.
184
+
185
+ ```bash
186
+ witan-code login
187
+ ```
188
+
189
+ The cache is shared with the `witan` CLI and keyed by `(issuer, client id)`, so
190
+ a prior `witan login` against the same deployment already covers witan-code —
191
+ and this command covers `witan` in turn.
192
+
193
+ ## `logout`
194
+
195
+ Forget the cached token for the configured deployment. Shared cache, so this
196
+ logs the `witan` CLI out as well.
197
+
198
+ No parameters.
199
+
200
+ ```bash
201
+ witan-code logout
202
+ ```
203
+
204
+ ## `whoami`
205
+
206
+ Show the identity the CLI presents to the deployed service: the matched target
207
+ (if any), endpoint, username, email, `sub`, and token expiry. Claims are
208
+ decoded for display only — the CLI never verifies the JWT; the deployment does.
209
+
210
+ Exits 1 when there is no valid cached token (run `witan-code login`).
211
+
212
+ No parameters.
213
+
214
+ ```bash
215
+ witan-code whoami
216
+ ```
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "witan-code"
3
- version = "0.6.0"
3
+ version = "0.8.0"
4
4
  description = "witan-code — tree-sitter code graph + cross-repo bridge (mounts under `witan code`)"
5
5
  readme = "README.md"
6
6
  license = "BSD-3-Clause"
@@ -11,8 +11,12 @@ classifiers = [
11
11
  ]
12
12
  dependencies = [
13
13
  "agent-config-kit>=0.4,<1",
14
- "witan-core[cli]>=0.2,<1",
15
- "fastmcp>=3.4.2,<4",
14
+ # `remote`: the ADR-0005 client stack (OIDC device grant + MCP-client
15
+ # proxy) behind `witan-code login` and the read commands' remote mode.
16
+ # Costs nothing extra in practice — fastmcp is already required here and
17
+ # itself depends on httpx2, the extra's only other dependency.
18
+ "witan-core[cli,remote]>=0.6,<1",
19
+ "fastmcp>=3.4.2,<5",
16
20
  "cyclopts>=4,<5",
17
21
  # [targets.<name>] override models (config.py) — also transitively pulled
18
22
  # in by fastmcp, declared explicitly since config.py imports it directly.
@@ -43,6 +47,14 @@ dependencies = [
43
47
  "rich>=13",
44
48
  ]
45
49
 
50
+ [project.optional-dependencies]
51
+ # The io.modelcontextprotocol/tasks extension (SEP-2663), which lets a client
52
+ # poll a long `code_reindex` instead of holding the tool call open. Optional
53
+ # because it exists only for fastmcp 4.x while the pin above still spans 3.4.x,
54
+ # and because it pulls a Docket/Redis stack that the default in-process
55
+ # `memory://` backend does not need. server.py registers it when importable.
56
+ tasks = ["fastmcp-tasks>=4.0.0b1,<5"]
57
+
46
58
  [project.urls]
47
59
  Homepage = "https://github.com/mitodl/agent-kit/tree/main/mcp/servers/witan-code"
48
60
  Repository = "https://github.com/mitodl/agent-kit"
@@ -65,7 +77,10 @@ agent-config-kit = { workspace = true }
65
77
  witan-core = { workspace = true }
66
78
 
67
79
  [dependency-groups]
68
- test = ["pytest>=8"]
80
+ # fastmcp-tasks: the `tasks` extra. Without it CI would only ever exercise the
81
+ # extension-absent branch, and `code_reindex`'s task declaration would go
82
+ # untested — the failure mode there is the server refusing to start at all.
83
+ test = ["pytest>=8", "fastmcp-tasks>=4.0.0b1,<5"]
69
84
 
70
85
  [tool.pytest.ini_options]
71
86
  pythonpath = ["."]
@@ -75,7 +90,7 @@ testpaths = ["tests"]
75
90
  packages = ["witan_code"]
76
91
 
77
92
  [tool.bumpversion]
78
- current_version = "0.6.0"
93
+ current_version = "0.8.0"
79
94
  allow_dirty = true
80
95
 
81
96
  [[tool.bumpversion.files]]