knot 1.9.3

Codebase Graph + Vector RAG Indexer for Java, TypeScript, JavaScript, Kotlin, Rust, Python, Groovy, C/C++, C#, Build Systems, and HTML/CSS codebases
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
# MCP Dispatch API Plan (knot 1.9.3)

**Status:** proposed
**Target release:** knot 1.9.3
**Driver:** knot-server needs to expose the exact same MCP tool surface over an
HTTP `/mcp` endpoint without re-implementing (and therefore drifting from) the
tool table that `knot-mcp` serves over stdio.

---

## 1. Problem statement

`KnotMcpHandler` already owns the canonical MCP tool surface, but it is only
reachable through the `rust_mcp_sdk::mcp_server::ServerHandler` trait:

```rust
async fn handle_list_tools_request(
    &self,
    _request: Option<PaginatedRequestParams>,
    _runtime: Arc<dyn McpServer>,          // <-- unusable for embedders
) -> Result<ListToolsResult, RpcError>;

async fn handle_call_tool_request(
    &self,
    params: CallToolRequestParams,
    _runtime: Arc<dyn McpServer>,          // <-- unusable for embedders
) -> Result<CallToolResult, CallToolError>;
```

Both methods demand an `Arc<dyn McpServer>`. That trait has ~20 required
methods and is only ever constructed by the SDK's own
`server_runtime::create_server_instance`, which is not public API. An embedder
that wants to drive the tools from its own transport (knot-server's stateless
`/mcp`) therefore has two bad options:

1. Fabricate an `Arc<dyn McpServer>` — impractical.
2. Duplicate the 5-arm dispatch `match` and the `Tool::tool()` list downstream —
   works today, drifts tomorrow. Every new knot tool would silently fail to
   appear in knot-server until someone remembers to sync.

Note that both parameters are already named `_runtime` in knot: the tool
implementations never use them. The coupling is purely structural.

## 2. Objective

Promote the tool table and the dispatch `match` to public, runtime-free API on
`KnotMcpHandler`, and reduce the `ServerHandler` impl to a thin delegation.
After this change, adding a tool to knot automatically adds it to every
embedder, by construction rather than by convention.

## 3. Scope

**In scope**

- `src/mcp_handler.rs`: two new public associated items + delegation.
- Extraction of the dry-run message to a named constant so both surfaces (and
  their tests) assert the same string.
- Unit tests covering the new API and the delegation invariants.
- CHANGELOG + README note.

**Out of scope**

- Any change to tool behaviour, schemas, descriptions or output formatting.
- Any change to `build_server_details()`.
- Any HTTP transport inside knot. knot stays stdio-only; HTTP lives in
  knot-server.
- Any change to `knot-mcp`, `knot-indexer` or the `knot` CLI binaries.

## 4. Public API contract

```rust
impl KnotMcpHandler {
    /// The canonical MCP tool surface.
    ///
    /// Single source of truth shared by the stdio server (`knot-mcp`) and by
    /// any embedder that drives the tools from its own transport (for example
    /// knot-server's stateless `/mcp` endpoint). Adding a tool here makes it
    /// visible on every surface at once.
    pub fn tools() -> Vec<Tool>;

    /// Dispatch a tool call without an `Arc<dyn McpServer>` runtime.
    ///
    /// Behaviourally identical to `handle_call_tool_request`, which delegates
    /// here: the runtime argument was never read by any tool.
    pub async fn dispatch(
        &self,
        params: CallToolRequestParams,
    ) -> Result<CallToolResult, CallToolError>;
}

/// Error text returned by `dispatch` when the handler was built with
/// `new_dry_run()`.
pub const DRY_RUN_MESSAGE: &str = "...";
```

### 4.1 Invariants the tests must pin

| # | Invariant | Why it matters |
|---|---|---|
| I1 | `tools()` returns exactly the tools advertised by `handle_list_tools_request` | The whole point: no second list to keep in sync |
| I2 | `dispatch` returns exactly what `handle_call_tool_request` returns, for every input | Embedders must not observe a different surface than stdio clients |
| I3 | The dry-run guard lives in `dispatch`, not in the trait method | Otherwise an embedder bypasses it and hits `None` databases |
| I4 | Unknown tool names yield `CallToolError::unknown_tool` | Callers map this to `CallToolResult { is_error: true }`, per SDK runtime behaviour |
| I5 | `tools()` is a *free* function of no state | Lets embedders answer `tools/list` before any DB connection exists |

### 4.2 Backwards compatibility

This is strictly additive. `ServerHandler` keeps both methods with identical
signatures and identical observable behaviour, so `knot-mcp` and every existing
MCP client are unaffected. The release is a patch bump (1.9.2 → 1.9.3).

---

## 5. BDD specification

Written as executable intent; each scenario maps to one or more `#[test]` /
`#[tokio::test]` functions in §6.

```gherkin
Feature: Runtime-free MCP tool surface
  As an embedder of the knot library
  I want to list and invoke MCP tools without an Arc<dyn McpServer>
  So that I can serve the exact knot tool surface over my own transport

  Background:
    Given the knot MCP tool set is search_hybrid_context, find_callers,
      explore_file, list_repo_dependencies and list_repositories

  Scenario: The tool table is reachable without a handler instance
    When I call KnotMcpHandler::tools()
    Then I receive 5 tools
    And their names are exactly the tool set
    And no database connection was required

  Scenario: The trait method and the free function agree
    Given a dry-run handler
    When I call handle_list_tools_request
    And I call KnotMcpHandler::tools()
    Then both return the same tool names in the same order

  Scenario: Every advertised tool carries a usable schema
    When I call KnotMcpHandler::tools()
    Then every tool has a non-empty name
    And every tool has a non-empty description
    And every tool declares an object input schema

  Scenario: Dispatching an unknown tool is a tool error, not a panic
    Given a dry-run handler
    When I dispatch a call to "no_such_tool"
    Then I receive Err(CallToolError)
    And converting it to a CallToolResult yields is_error = true

  Scenario: A dry-run handler refuses to execute tools
    Given a dry-run handler
    When I dispatch a call to "search_hybrid_context"
    Then I receive Err(CallToolError)
    And the message equals DRY_RUN_MESSAGE

  Scenario: The dry-run guard cannot be bypassed through dispatch
    Given a dry-run handler
    When I dispatch a call to each of the 5 tools in turn
    Then every call is refused with DRY_RUN_MESSAGE

  Scenario: The trait call path and the direct call path agree
    Given a dry-run handler
    When I dispatch a call to "explore_file" directly
    And I would call handle_call_tool_request with the same params
    Then both paths produce the same error message

  Scenario: Offline handlers report missing databases, not dry-run
    Given a handler with no databases but dry_run = false
    When I dispatch a call to "search_hybrid_context"
    Then I receive Err(CallToolError)
    And the message mentions offline mode
    # Guards the ordering of the two guards: dry_run is checked first,
    # the per-tool database guard second.
```

---

## 6. TDD plan

Strict red → green → refactor. Every cycle starts by writing a test that
**fails to compile or fails to pass** against the current tree.

All tests live in `src/mcp_handler.rs` under the existing `#[cfg(test)] mod
tests`, next to the current `build_server_details` tests. No new files, no new
dev-dependencies. `#[tokio::test]` is already available via the `tokio` dep.

### Cycle 1 — `tools()` exists and is correct

**RED.** Add:

```rust
const EXPECTED_TOOLS: [&str; 5] = [
    "search_hybrid_context",
    "find_callers",
    "explore_file",
    "list_repo_dependencies",
    "list_repositories",
];

#[test]
fn tools_returns_the_full_surface() {
    let names: Vec<String> = KnotMcpHandler::tools().into_iter().map(|t| t.name).collect();
    assert_eq!(names, EXPECTED_TOOLS);
}
```

Fails to compile: no `tools()`.

**GREEN.** Add `pub fn tools() -> Vec<Tool>` returning the five `Tool::tool()`
calls in the order currently hardcoded in `handle_list_tools_request`.

**REFACTOR.** Rewrite `handle_list_tools_request` as:

```rust
Ok(ListToolsResult { tools: Self::tools(), meta: None, next_cursor: None })
```

### Cycle 2 — the two list paths cannot diverge (I1)

**RED.**

```rust
#[tokio::test]
async fn list_tools_request_matches_tools_fn() {
    let handler = KnotMcpHandler::new_dry_run();
    let via_trait = handler
        .handle_list_tools_request(None, dummy_runtime())
        .await
        .expect("list tools");
    let via_fn = KnotMcpHandler::tools();
    assert_eq!(
        via_trait.tools.iter().map(|t| &t.name).collect::<Vec<_>>(),
        via_fn.iter().map(|t| &t.name).collect::<Vec<_>>(),
    );
}
```

**Blocker to resolve first:** `handle_list_tools_request` needs an
`Arc<dyn McpServer>`, which is precisely what we cannot build. Two ways out —
pick one during implementation:

- **(a) Preferred.** Do not call the trait method at all. Instead assert the
  delegation structurally: a source-level guard test that reads
  `include_str!("mcp_handler.rs")` and asserts that the body of
  `handle_list_tools_request` contains `Self::tools()` and does **not** contain
  `Tool::tool()`. Crude but honest, cheap, and it fails loudly if someone
  re-inlines the list. This mirrors the drift-guard pattern already used in
  knot-server's `metrics.rs`.
- **(b)** Skip the cross-path assertion for `list_tools` and rely on the fact
  that the delegation is a one-liner reviewed in the diff.

Choose (a). It is the only mechanical protection available, and the invariant it
protects (I1) is the reason this plan exists.

**GREEN.** Already green after Cycle 1's refactor; the guard test simply locks
it in.

### Cycle 3 — tool schemas are well-formed

**RED.**

```rust
#[test]
fn every_tool_has_name_description_and_object_schema() {
    for tool in KnotMcpHandler::tools() {
        assert!(!tool.name.is_empty(), "empty tool name");
        let desc = tool.description.as_deref().unwrap_or_default();
        assert!(!desc.is_empty(), "{} has no description", tool.name);
        assert_eq!(tool.input_schema.type_, "object", "{}", tool.name);
    }
}
```

This should pass immediately (the `#[mcp_tool]` macro guarantees it). Keep it:
it is the regression net for a future hand-written tool.

### Cycle 4 — `DRY_RUN_MESSAGE` constant

**RED.**

```rust
#[test]
fn dry_run_message_is_descriptive() {
    assert!(DRY_RUN_MESSAGE.contains("dry-run mode"));
    assert!(DRY_RUN_MESSAGE.contains("Database connections are not available"));
}
```

Fails to compile: no constant.

**GREEN.** Extract the existing literal from `handle_call_tool_request` into

```rust
pub const DRY_RUN_MESSAGE: &str =
    "Server is running in dry-run mode. Database connections are not available. \
     This mode is used for protocol validation and quality checks only.";
```

and reference it from the guard. The string must stay byte-identical to today's
so no client observes a change.

### Cycle 5 — `dispatch()` refuses in dry-run mode (I3)

**RED.**

```rust
#[tokio::test]
async fn dispatch_refuses_in_dry_run_mode() {
    let handler = KnotMcpHandler::new_dry_run();
    let params = CallToolRequestParams {
        name: "search_hybrid_context".into(),
        arguments: None,
        ..Default::default()
    };
    let err = handler.dispatch(params).await.expect_err("dry-run must refuse");
    assert_eq!(err.to_string(), DRY_RUN_MESSAGE);
}
```

Fails to compile: no `dispatch()`.

**GREEN.** Add `dispatch()` with the dry-run guard followed by the `match`
lifted verbatim from `handle_call_tool_request`.

**REFACTOR.** Rewrite `handle_call_tool_request` as `self.dispatch(params).await`.
Add the same source-level drift guard as Cycle 2: the trait body must contain
`self.dispatch(` and must not contain `SearchHybridContextTool::handle`.

> Confirm during implementation whether `CallToolRequestParams` implements
> `Default`. If it does not, build the struct with all fields spelled out and
> add a small `fn call_params(name: &str) -> CallToolRequestParams` test helper
> so the other cycles stay readable.

### Cycle 6 — every tool is guarded (I3, exhaustively)

**RED.**

```rust
#[tokio::test]
async fn dispatch_refuses_every_tool_in_dry_run_mode() {
    let handler = KnotMcpHandler::new_dry_run();
    for name in EXPECTED_TOOLS {
        let err = handler
            .dispatch(call_params(name))
            .await
            .expect_err("dry-run must refuse");
        assert_eq!(err.to_string(), DRY_RUN_MESSAGE, "tool {name}");
    }
}
```

Green after Cycle 5. Its value is future-proofing: a new tool wired into
`dispatch` after the guard would break this test.

### Cycle 7 — unknown tools (I4)

**RED.**

```rust
#[tokio::test]
async fn dispatch_rejects_unknown_tool() {
    // dry_run = false so the unknown-tool arm is reached rather than the guard.
    let handler = KnotMcpHandler {
        vector_db: None,
        graph_db: None,
        embedder: None,
        dry_run: false,
    };
    let err = handler
        .dispatch(call_params("no_such_tool"))
        .await
        .expect_err("unknown tool must fail");
    assert!(err.to_string().contains("no_such_tool"));

    let result: CallToolResult = err.into();
    assert_eq!(result.is_error, Some(true));
}
```

The second half pins the conversion the SDK runtime performs
(`mcp_server_runtime.rs`: `CallToolError` → `CallToolResult { is_error: true }`,
delivered as a *successful* JSON-RPC response). Embedders must replicate it, so
knot should assert it.

### Cycle 8 — guard ordering (offline vs dry-run)

**RED.**

```rust
#[tokio::test]
async fn offline_handler_reports_missing_databases_not_dry_run() {
    let handler = KnotMcpHandler {
        vector_db: None,
        graph_db: None,
        embedder: None,
        dry_run: false,
    };
    let err = handler
        .dispatch(call_params("search_hybrid_context"))
        .await
        .expect_err("offline must fail");
    let msg = err.to_string();
    assert_ne!(msg, DRY_RUN_MESSAGE);
    assert!(msg.contains("offline mode"), "unexpected message: {msg}");
}
```

Green by construction; documents that `dry_run` is checked first and the
per-tool database guard second, which is the behaviour knot-server will rely on
when it builds a handler with `dry_run: false` and real `Arc`s.

### Cycle 9 — refactor pass

With all tests green:

- Collapse duplication between `EXPECTED_TOOLS` and `tools()` if a clean
  expression exists; if not, leave the literal array — an independently written
  expectation is the point of the test.
- Re-read `dispatch` for `clippy::cognitive_complexity` (warn-level in this
  crate). A 5-arm match plus one guard is well under the threshold.
- Confirm no `#[allow]` was introduced.

---

## 7. Implementation sketch

`src/mcp_handler.rs`, after the `impl KnotMcpHandler` block that holds `new` and
`new_dry_run`:

```rust
/// Error text returned when a dry-run handler is asked to execute a tool.
pub const DRY_RUN_MESSAGE: &str =
    "Server is running in dry-run mode. Database connections are not available. \
     This mode is used for protocol validation and quality checks only.";

impl KnotMcpHandler {
    /// The canonical MCP tool surface, independent of any transport or runtime.
    ///
    /// `knot-mcp` serves it over stdio; embedders such as knot-server serve the
    /// same list over HTTP. Keeping one list here is what makes those surfaces
    /// identical by construction.
    pub fn tools() -> Vec<Tool> {
        vec![
            SearchHybridContextTool::tool(),
            FindCallersTool::tool(),
            ExploreFileTool::tool(),
            ListRepoDependenciesTool::tool(),
            ListRepositoriesTool::tool(),
        ]
    }

    /// Execute a tool call without an `Arc<dyn McpServer>`.
    ///
    /// The SDK's `ServerHandler` demands a runtime handle that no tool reads;
    /// this entry point drops it so an embedder can drive the tools from its
    /// own transport. `handle_call_tool_request` delegates here, so both paths
    /// are the same code.
    pub async fn dispatch(
        &self,
        params: CallToolRequestParams,
    ) -> std::result::Result<CallToolResult, CallToolError> {
        if self.dry_run {
            return Err(CallToolError::from_message(DRY_RUN_MESSAGE.to_string()));
        }

        match params.name.as_str() {
            "search_hybrid_context" => SearchHybridContextTool::handle(params, self).await,
            "find_callers" => FindCallersTool::handle(params, self).await,
            "explore_file" => ExploreFileTool::handle(params, self).await,
            "list_repo_dependencies" => ListRepoDependenciesTool::handle(params, self).await,
            "list_repositories" => ListRepositoriesTool::handle(params, self).await,
            _ => Err(CallToolError::unknown_tool(params.name)),
        }
    }
}
```

And the trait impl shrinks to:

```rust
#[async_trait]
impl ServerHandler for KnotMcpHandler {
    async fn handle_list_tools_request(
        &self,
        _request: Option<PaginatedRequestParams>,
        _runtime: Arc<dyn McpServer>,
    ) -> std::result::Result<ListToolsResult, RpcError> {
        Ok(ListToolsResult {
            tools: Self::tools(),
            meta: None,
            next_cursor: None,
        })
    }

    async fn handle_call_tool_request(
        &self,
        params: CallToolRequestParams,
        _runtime: Arc<dyn McpServer>,
    ) -> std::result::Result<CallToolResult, CallToolError> {
        self.dispatch(params).await
    }
}
```

Net change: roughly +30 lines of API and docs, −12 lines from the trait impl,
plus tests.

---

## 8. Risks

| Risk | Mitigation |
|---|---|
| Someone re-inlines the tool list or the match into the trait impl | Source-level drift guards (Cycles 2 and 5) |
| `DRY_RUN_MESSAGE` extraction silently changes the string | Cycle 4 asserts the substrings; diff review confirms byte equality |
| `CallToolRequestParams` has no `Default`, breaking the test helpers | Resolve in Cycle 5 with an explicit constructor helper |
| Downstream pins `knot = "1.9.2"` and never sees the API | knot-server bumps to `1.9.3` as part of its own plan |

---

## 9. Quality gates

Per `AGENTS.md`, run the `validator` subagent after implementation:

1. `cargo fmt`
2. `cargo clippy --all-targets --all-features -- -D warnings`
3. `cargo test`
4. `./tests/run_all_e2e_fast.sh`

No `#[allow(...)]`. No `unsafe`. Edition 2024.

The E2E suite is the real proof of I2: it drives `knot-mcp` over stdio through
the unchanged trait path. If the tool surface is intact there, the delegation is
correct.

---

## 10. Release checklist

- [ ] Cycles 1–9 complete, all tests green
- [ ] `validator` clean
- [ ] `README.md`: MCP tools section notes that `KnotMcpHandler::tools()` and
      `::dispatch()` are the supported embedding API
- [ ] `CHANGELOG.md`: new `## [1.9.3]` entry under *Added* —
      "`KnotMcpHandler::tools()` and `KnotMcpHandler::dispatch()`: runtime-free
      access to the MCP tool surface for library embedders" — and under
      *Changed* — "`ServerHandler` methods now delegate to the new API; no
      behavioural change for MCP clients"
- [ ] `Cargo.toml` version → `1.9.3`
- [ ] **Ask the maintainer before publishing to crates.io** (`AGENTS.md`)
- [ ] Downstream: knot-server switches from `[patch.crates-io]` to
      `knot = "1.9.3"` before its own release