witan-code 0.6.0__tar.gz → 0.7.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 (79) hide show
  1. {witan_code-0.6.0 → witan_code-0.7.0}/CHANGELOG.md +29 -0
  2. {witan_code-0.6.0 → witan_code-0.7.0}/PKG-INFO +5 -3
  3. {witan_code-0.6.0 → witan_code-0.7.0}/pyproject.toml +16 -5
  4. witan_code-0.7.0/tests/test_tasks.py +104 -0
  5. {witan_code-0.6.0 → witan_code-0.7.0}/witan_code/elicit.py +6 -2
  6. {witan_code-0.6.0 → witan_code-0.7.0}/witan_code/server.py +38 -3
  7. {witan_code-0.6.0 → witan_code-0.7.0}/.gitignore +0 -0
  8. {witan_code-0.6.0 → witan_code-0.7.0}/README.md +0 -0
  9. {witan_code-0.6.0 → witan_code-0.7.0}/config/claude.json +0 -0
  10. {witan_code-0.6.0 → witan_code-0.7.0}/config/copilot.json +0 -0
  11. {witan_code-0.6.0 → witan_code-0.7.0}/config/pi.json +0 -0
  12. {witan_code-0.6.0 → witan_code-0.7.0}/docs/BRANCH_INDEXING.md +0 -0
  13. {witan_code-0.6.0 → witan_code-0.7.0}/docs/CLI_REFERENCE.md +0 -0
  14. {witan_code-0.6.0 → witan_code-0.7.0}/docs/EDGE_PRECISION_TIERS.md +0 -0
  15. {witan_code-0.6.0 → witan_code-0.7.0}/docs/PACKAGE_MAP.md +0 -0
  16. {witan_code-0.6.0 → witan_code-0.7.0}/docs/STAGE2_STITCHING.md +0 -0
  17. {witan_code-0.6.0 → witan_code-0.7.0}/docs/SYMBOL_FORMAT.md +0 -0
  18. {witan_code-0.6.0 → witan_code-0.7.0}/docs/SYMBOL_TABLE.md +0 -0
  19. {witan_code-0.6.0 → witan_code-0.7.0}/docs/USER_GUIDE.md +0 -0
  20. {witan_code-0.6.0 → witan_code-0.7.0}/install.sh +0 -0
  21. {witan_code-0.6.0 → witan_code-0.7.0}/tests/__init__.py +0 -0
  22. {witan_code-0.6.0 → witan_code-0.7.0}/tests/conftest.py +0 -0
  23. {witan_code-0.6.0 → witan_code-0.7.0}/tests/test_branches.py +0 -0
  24. {witan_code-0.6.0 → witan_code-0.7.0}/tests/test_bridge.py +0 -0
  25. {witan_code-0.6.0 → witan_code-0.7.0}/tests/test_cli_hooks.py +0 -0
  26. {witan_code-0.6.0 → witan_code-0.7.0}/tests/test_cli_output_format.py +0 -0
  27. {witan_code-0.6.0 → witan_code-0.7.0}/tests/test_config.py +0 -0
  28. {witan_code-0.6.0 → witan_code-0.7.0}/tests/test_config_targets.py +0 -0
  29. {witan_code-0.6.0 → witan_code-0.7.0}/tests/test_context.py +0 -0
  30. {witan_code-0.6.0 → witan_code-0.7.0}/tests/test_crossrepo.py +0 -0
  31. {witan_code-0.6.0 → witan_code-0.7.0}/tests/test_edges.py +0 -0
  32. {witan_code-0.6.0 → witan_code-0.7.0}/tests/test_elicit.py +0 -0
  33. {witan_code-0.6.0 → witan_code-0.7.0}/tests/test_enrichment.py +0 -0
  34. {witan_code-0.6.0 → witan_code-0.7.0}/tests/test_graph.py +0 -0
  35. {witan_code-0.6.0 → witan_code-0.7.0}/tests/test_hooks.py +0 -0
  36. {witan_code-0.6.0 → witan_code-0.7.0}/tests/test_indexer.py +0 -0
  37. {witan_code-0.6.0 → witan_code-0.7.0}/tests/test_languages.py +0 -0
  38. {witan_code-0.6.0 → witan_code-0.7.0}/tests/test_maintenance.py +0 -0
  39. {witan_code-0.6.0 → witan_code-0.7.0}/tests/test_package_map.py +0 -0
  40. {witan_code-0.6.0 → witan_code-0.7.0}/tests/test_repo.py +0 -0
  41. {witan_code-0.6.0 → witan_code-0.7.0}/tests/test_server.py +0 -0
  42. {witan_code-0.6.0 → witan_code-0.7.0}/tests/test_setup.py +0 -0
  43. {witan_code-0.6.0 → witan_code-0.7.0}/tests/test_stitch.py +0 -0
  44. {witan_code-0.6.0 → witan_code-0.7.0}/tests/test_symbol_table.py +0 -0
  45. {witan_code-0.6.0 → witan_code-0.7.0}/tests/test_visualize.py +0 -0
  46. {witan_code-0.6.0 → witan_code-0.7.0}/uv.lock +0 -0
  47. {witan_code-0.6.0 → witan_code-0.7.0}/witan_code/__init__.py +0 -0
  48. {witan_code-0.6.0 → witan_code-0.7.0}/witan_code/__main__.py +0 -0
  49. {witan_code-0.6.0 → witan_code-0.7.0}/witan_code/bridge.py +0 -0
  50. {witan_code-0.6.0 → witan_code-0.7.0}/witan_code/bridge_extractors.py +0 -0
  51. {witan_code-0.6.0 → witan_code-0.7.0}/witan_code/cli.py +0 -0
  52. {witan_code-0.6.0 → witan_code-0.7.0}/witan_code/config.py +0 -0
  53. {witan_code-0.6.0 → witan_code-0.7.0}/witan_code/context.py +0 -0
  54. {witan_code-0.6.0 → witan_code-0.7.0}/witan_code/edges.py +0 -0
  55. {witan_code-0.6.0 → witan_code-0.7.0}/witan_code/extensions/pi/codegraph.ts +0 -0
  56. {witan_code-0.6.0 → witan_code-0.7.0}/witan_code/graph.py +0 -0
  57. {witan_code-0.6.0 → witan_code-0.7.0}/witan_code/hooks.py +0 -0
  58. {witan_code-0.6.0 → witan_code-0.7.0}/witan_code/indexer.py +0 -0
  59. {witan_code-0.6.0 → witan_code-0.7.0}/witan_code/maintenance.py +0 -0
  60. {witan_code-0.6.0 → witan_code-0.7.0}/witan_code/output.py +0 -0
  61. {witan_code-0.6.0 → witan_code-0.7.0}/witan_code/package_map.py +0 -0
  62. {witan_code-0.6.0 → witan_code-0.7.0}/witan_code/queries/bridge.gq +0 -0
  63. {witan_code-0.6.0 → witan_code-0.7.0}/witan_code/queries/code_mutations.gq +0 -0
  64. {witan_code-0.6.0 → witan_code-0.7.0}/witan_code/queries/code_read.gq +0 -0
  65. {witan_code-0.6.0 → witan_code-0.7.0}/witan_code/queries/delete.gq +0 -0
  66. {witan_code-0.6.0 → witan_code-0.7.0}/witan_code/queries_ts/bash.scm +0 -0
  67. {witan_code-0.6.0 → witan_code-0.7.0}/witan_code/queries_ts/hcl.scm +0 -0
  68. {witan_code-0.6.0 → witan_code-0.7.0}/witan_code/queries_ts/python.scm +0 -0
  69. {witan_code-0.6.0 → witan_code-0.7.0}/witan_code/queries_ts/sql.scm +0 -0
  70. {witan_code-0.6.0 → witan_code-0.7.0}/witan_code/queries_ts/typescript.scm +0 -0
  71. {witan_code-0.6.0 → witan_code-0.7.0}/witan_code/queries_ts/yaml.scm +0 -0
  72. {witan_code-0.6.0 → witan_code-0.7.0}/witan_code/repo.py +0 -0
  73. {witan_code-0.6.0 → witan_code-0.7.0}/witan_code/schema/bridge-schema.pg +0 -0
  74. {witan_code-0.6.0 → witan_code-0.7.0}/witan_code/schema/code-schema.pg +0 -0
  75. {witan_code-0.6.0 → witan_code-0.7.0}/witan_code/setup.py +0 -0
  76. {witan_code-0.6.0 → witan_code-0.7.0}/witan_code/skills/witan-code/SKILL.md +0 -0
  77. {witan_code-0.6.0 → witan_code-0.7.0}/witan_code/stitch.py +0 -0
  78. {witan_code-0.6.0 → witan_code-0.7.0}/witan_code/store.py +0 -0
  79. {witan_code-0.6.0 → witan_code-0.7.0}/witan_code/visualize.py +0 -0
@@ -6,6 +6,35 @@ 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.7.0] - 2026-07-30
10
+
11
+ ### Changed
12
+
13
+ - **Requires `witan-core>=0.5`** (was `>=0.2`) — the server now imports
14
+ `witan_core.caching` and `elicit.MRTRElicitationMiddleware`, neither of which
15
+ exists below that.
16
+ - **`code_reindex` is now async and no longer blocks the event loop.** It was a
17
+ plain `def`, so a multi-minute index stalled every other request on the server
18
+ for its whole run; the indexer now runs on a thread.
19
+ - **`tools/list` declares a cache directive** — `ttlMs=300000`,
20
+ `cacheScope=private`.
21
+ - **Elicitation works on the stateless protocol era again** — the index-now
22
+ confirms and the repo prompt had been silently returning their
23
+ non-interactive defaults on any MCP 2026-07-28 connection. See the
24
+ `witan-core` 0.5.0 entry.
25
+
26
+ ### Added
27
+
28
+ - **`code_reindex` accepts task-augmented execution** (`io.modelcontextprotocol/tasks`,
29
+ SEP-2663) via the new optional `witan-code[tasks]` extra: a client can take a
30
+ handle and poll rather than holding the tool call open for the whole rebuild.
31
+ Opt-in per call — a client that does not ask gets the same completed result as
32
+ before. Without the extra the tool stays synchronous; the extra is separate
33
+ because it pulls a Docket/Redis stack most installs never need, and because it
34
+ requires FastMCP 4 while this package still supports 3.4.x. Note that while
35
+ 4.0 is still a pre-release, `witan-code[tasks]` needs `--prerelease=allow`
36
+ under uv; the base package does not.
37
+
9
38
  ## [0.6.0] - 2026-07-21
10
39
 
11
40
  ### Fixed
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: witan-code
3
- Version: 0.6.0
3
+ Version: 0.7.0
4
4
  Summary: witan-code — tree-sitter code graph + cross-repo bridge (mounts under `witan code`)
5
5
  Project-URL: Homepage, https://github.com/mitodl/agent-kit/tree/main/mcp/servers/witan-code
6
6
  Project-URL: Repository, https://github.com/mitodl/agent-kit
@@ -12,7 +12,7 @@ Classifier: Programming Language :: Python :: 3
12
12
  Requires-Python: >=3.11
13
13
  Requires-Dist: agent-config-kit<1,>=0.4
14
14
  Requires-Dist: cyclopts<5,>=4
15
- Requires-Dist: fastmcp<4,>=3.4.2
15
+ Requires-Dist: fastmcp<5,>=3.4.2
16
16
  Requires-Dist: pydantic<3,>=2
17
17
  Requires-Dist: pyyaml<7,>=6
18
18
  Requires-Dist: rich>=13
@@ -25,7 +25,9 @@ Requires-Dist: tree-sitter-sql<0.4,>=0.3
25
25
  Requires-Dist: tree-sitter-typescript<0.24,>=0.23
26
26
  Requires-Dist: tree-sitter-yaml<0.8,>=0.7
27
27
  Requires-Dist: tree-sitter<0.26,>=0.25
28
- Requires-Dist: witan-core[cli]<1,>=0.2
28
+ Requires-Dist: witan-core[cli]<1,>=0.5
29
+ Provides-Extra: tasks
30
+ Requires-Dist: fastmcp-tasks<5,>=4.0.0b1; extra == 'tasks'
29
31
  Description-Content-Type: text/markdown
30
32
 
31
33
  # witan-code
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "witan-code"
3
- version = "0.6.0"
3
+ version = "0.7.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,8 @@ 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
+ "witan-core[cli]>=0.5,<1",
15
+ "fastmcp>=3.4.2,<5",
16
16
  "cyclopts>=4,<5",
17
17
  # [targets.<name>] override models (config.py) — also transitively pulled
18
18
  # in by fastmcp, declared explicitly since config.py imports it directly.
@@ -43,6 +43,14 @@ dependencies = [
43
43
  "rich>=13",
44
44
  ]
45
45
 
46
+ [project.optional-dependencies]
47
+ # The io.modelcontextprotocol/tasks extension (SEP-2663), which lets a client
48
+ # poll a long `code_reindex` instead of holding the tool call open. Optional
49
+ # because it exists only for fastmcp 4.x while the pin above still spans 3.4.x,
50
+ # and because it pulls a Docket/Redis stack that the default in-process
51
+ # `memory://` backend does not need. server.py registers it when importable.
52
+ tasks = ["fastmcp-tasks>=4.0.0b1,<5"]
53
+
46
54
  [project.urls]
47
55
  Homepage = "https://github.com/mitodl/agent-kit/tree/main/mcp/servers/witan-code"
48
56
  Repository = "https://github.com/mitodl/agent-kit"
@@ -65,7 +73,10 @@ agent-config-kit = { workspace = true }
65
73
  witan-core = { workspace = true }
66
74
 
67
75
  [dependency-groups]
68
- test = ["pytest>=8"]
76
+ # fastmcp-tasks: the `tasks` extra. Without it CI would only ever exercise the
77
+ # extension-absent branch, and `code_reindex`'s task declaration would go
78
+ # untested — the failure mode there is the server refusing to start at all.
79
+ test = ["pytest>=8", "fastmcp-tasks>=4.0.0b1,<5"]
69
80
 
70
81
  [tool.pytest.ini_options]
71
82
  pythonpath = ["."]
@@ -75,7 +86,7 @@ testpaths = ["tests"]
75
86
  packages = ["witan_code"]
76
87
 
77
88
  [tool.bumpversion]
78
- current_version = "0.6.0"
89
+ current_version = "0.7.0"
79
90
  allow_dirty = true
80
91
 
81
92
  [[tool.bumpversion.files]]
@@ -0,0 +1,104 @@
1
+ """`code_reindex` under the io.modelcontextprotocol/tasks extension (SEP-2663).
2
+
3
+ A full rebuild runs for minutes on a large repo, so a client can ask for the
4
+ call to run as a background task and poll it. The extension is an optional
5
+ dependency (`witan-code[tasks]`), and the declaration is gated on it — a
6
+ `task=True` tool with no extension registered makes the server refuse every
7
+ connection, so the gate is what keeps the extra optional rather than required.
8
+ """
9
+
10
+ import asyncio
11
+
12
+ import pytest
13
+
14
+ from .conftest import requires_stack
15
+
16
+ pytest.importorskip("fastmcp_tasks", reason="requires the `tasks` extra")
17
+
18
+
19
+ def _index(sample_repo, monkeypatch, *, as_task):
20
+ """Reindex ``sample_repo`` through a real MCP client, sync or tasked."""
21
+ from fastmcp import Client
22
+ from fastmcp_tasks import call_tool_task
23
+
24
+ from witan_code import config as cfg_mod
25
+ from witan_code import server as srv
26
+
27
+ # server.cfg was captured at import; refresh it for the test's env + store.
28
+ monkeypatch.setattr(srv, "cfg", cfg_mod.load())
29
+ srv._clients.clear()
30
+
31
+ async def _call():
32
+ async with Client(srv.mcp, mode="2026-07-28") as client:
33
+ arguments = {"path": str(sample_repo)}
34
+ if not as_task:
35
+ return (await client.call_tool("code_reindex", arguments)).data
36
+ handle = await call_tool_task(client, "code_reindex", arguments)
37
+ # The point of the extension: the handle comes back before the
38
+ # index does, so the client is free while the work runs.
39
+ assert (await handle.status()).task_id
40
+ return (await handle.result()).data
41
+
42
+ return asyncio.run(_call())
43
+
44
+
45
+ def test_extension_is_registered_when_installed():
46
+ # The import gate silently turning the extension off would leave every
47
+ # reindex synchronous with nothing else failing, so assert it directly.
48
+ from witan_code import server as srv
49
+
50
+ assert srv.TASKS_ENABLED
51
+
52
+
53
+ def test_server_still_serves_without_the_extra(monkeypatch):
54
+ """The default install has no `fastmcp_tasks`, and must still start.
55
+
56
+ Worth its own test because the failure is total rather than degraded: a
57
+ `task=True` tool whose extension is missing makes FastMCP reject every
58
+ connection, so a gate that stopped tracking the import would take the whole
59
+ server down for anyone who didn't install the extra.
60
+ """
61
+ import builtins
62
+ import importlib
63
+
64
+ from witan_code import server as srv
65
+
66
+ real_import = builtins.__import__
67
+
68
+ def _without_tasks(name, *args, **kwargs):
69
+ if name == "fastmcp_tasks":
70
+ raise ImportError("masked")
71
+ return real_import(name, *args, **kwargs)
72
+
73
+ monkeypatch.setattr(builtins, "__import__", _without_tasks)
74
+ try:
75
+ importlib.reload(srv)
76
+ assert srv.TASKS_ENABLED is False
77
+
78
+ async def _connect():
79
+ from fastmcp import Client
80
+
81
+ async with Client(srv.mcp, mode="2026-07-28") as client:
82
+ return await client.list_tools()
83
+
84
+ assert any(t.name == "code_reindex" for t in asyncio.run(_connect()))
85
+ finally:
86
+ # Other tests hold references through this module; put the real one back.
87
+ monkeypatch.undo()
88
+ importlib.reload(srv)
89
+
90
+
91
+ @requires_stack
92
+ def test_reindex_runs_as_a_task(sample_repo, monkeypatch):
93
+ stats = _index(sample_repo, monkeypatch, as_task=True)
94
+ assert stats["symbols"] >= 3
95
+ assert stats["errors"] == 0
96
+
97
+
98
+ @requires_stack
99
+ def test_reindex_still_answers_synchronously(sample_repo, monkeypatch):
100
+ # Task execution is the client's choice, not the server's: a client that
101
+ # doesn't ask must get the same completed result it always did.
102
+ stats = _index(sample_repo, monkeypatch, as_task=False)
103
+ assert stats["symbols"] >= 3
104
+ assert stats["errors"] == 0
@@ -19,18 +19,22 @@ Call sites in ``server.py``:
19
19
  Never call these from a tool that must stay non-interactive under automation
20
20
  — ``code_reindex`` never takes a ``Context`` (see its docstring), and
21
21
  ``code_search_symbol`` returns many results by design, not an error case.
22
+
23
+ A tool that does ask must also be safe to re-run up to the ask: on MCP
24
+ 2026-07-28 the client answers by retrying the whole call, so everything before
25
+ the prompt happens twice. Ask after the reads and before the write.
22
26
  """
23
27
 
24
28
  from __future__ import annotations
25
29
 
26
30
  from typing import TYPE_CHECKING
27
31
 
28
- from witan_core.elicit import confirm, text
32
+ from witan_core.elicit import MRTRElicitationMiddleware, confirm, text
29
33
 
30
34
  if TYPE_CHECKING:
31
35
  from fastmcp import Context
32
36
 
33
- __all__ = ["choose_repo", "confirm", "text"]
37
+ __all__ = ["MRTRElicitationMiddleware", "choose_repo", "confirm", "text"]
34
38
 
35
39
 
36
40
  async def choose_repo(
@@ -5,6 +5,7 @@ from pathlib import Path
5
5
  from typing import Literal
6
6
 
7
7
  from fastmcp import Context, FastMCP
8
+ from witan_core import caching
8
9
 
9
10
  from . import bridge_extractors
10
11
  from . import config as cfg_module
@@ -50,8 +51,34 @@ mcp = FastMCP(
50
51
  "Calls/References edges are heuristic (syntactic name resolution), not a "
51
52
  "precise call graph; code_find_references includes code_callers."
52
53
  ),
54
+ # Let clients cache this server's tool list instead of re-listing it every
55
+ # session. Scope stays private: a code graph is scoped to its repos.
56
+ **caching.hint_kwargs(),
53
57
  )
54
58
 
59
+ # Carries `elicit.confirm`/`elicit.text` asks over MCP 2026-07-28, which has no
60
+ # server→client back-channel to run them on. Inert on the handshake eras.
61
+ mcp.add_middleware(elicit.MRTRElicitationMiddleware())
62
+
63
+ # The `io.modelcontextprotocol/tasks` extension (SEP-2663), which lets a client
64
+ # take a handle on a long `code_reindex` and poll it instead of holding a tool
65
+ # call open for minutes. Optional (`witan-code[tasks]`): it exists only for
66
+ # fastmcp 4.x, and this package still supports the 3.4.x end of its pin. The
67
+ # flag has to gate the tool declaration too — a `task=True` tool refuses to
68
+ # serve at all when the extension is missing, rather than degrading.
69
+ #
70
+ # Note the backend defaults to in-process `memory://`, which is what a per-repo
71
+ # stdio server wants. A multi-replica deployment polling through a round-robin
72
+ # LB would need a shared Docket backend (FASTMCP_DOCKET_URL) — moot today, since
73
+ # indexing needs a git checkout the deployment doesn't have.
74
+ try:
75
+ from fastmcp_tasks import TasksExtension
76
+ except ImportError:
77
+ TASKS_ENABLED = False
78
+ else:
79
+ TASKS_ENABLED = True
80
+ mcp.add_extension(TasksExtension())
81
+
55
82
  # Client cache keyed by "store path|branch" ("" = main).
56
83
  _clients: dict[str, OmnigraphClient] = {}
57
84
 
@@ -831,8 +858,8 @@ async def code_interface_search(
831
858
  return _filter_by_precision(rows, min_precision)
832
859
 
833
860
 
834
- @mcp.tool
835
- def code_reindex(path: str | None = None, force: bool = False) -> dict:
861
+ @mcp.tool(task=TASKS_ENABLED)
862
+ async def code_reindex(path: str | None = None, force: bool = False) -> dict:
836
863
  """
837
864
  Index (or re-index) the current repo, or a subpath of it.
838
865
 
@@ -840,6 +867,12 @@ def code_reindex(path: str | None = None, force: bool = False) -> dict:
840
867
  skipped. Lazily creates the per-repo store on first run. Returns a summary of
841
868
  files scanned/indexed/skipped and symbols/edges written.
842
869
 
870
+ A full rebuild runs for minutes on a large repo, so this tool accepts
871
+ task-augmented execution (`io.modelcontextprotocol/tasks`): a client that
872
+ asks for it gets a task handle back immediately and polls `tasks/get`,
873
+ instead of holding one tool call open for the whole index. Asking is the
874
+ client's choice — omit it and the call runs to completion as it always has.
875
+
843
876
  Parameters
844
877
  ----------
845
878
  path:
@@ -849,7 +882,9 @@ def code_reindex(path: str | None = None, force: bool = False) -> dict:
849
882
  Re-index every file regardless of content hash.
850
883
  """
851
884
  target = Path(path) if path else (repo_module.root() or Path.cwd())
852
- stats = indexer.index_path(target, force=force, config=cfg)
885
+ # Off the event loop: indexing is CPU- and IO-bound and would otherwise
886
+ # stall every other request on this server for its whole run.
887
+ stats = await asyncio.to_thread(indexer.index_path, target, force=force, config=cfg)
853
888
  return {
854
889
  "path": str(target),
855
890
  "scanned": stats.scanned,
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes