fix(monorepo): align get_context tool contract

Author: maehwasoo

apps/api/src/ailss_api/mcp_runtime.py

@@ -55,7 +55,7 @@ def create_mcp_server_from_env() -> FastMCP:
         openai_client=OpenAI(api_key=openai_api_key),
         diagnostics=ToolFailureDiagnostics(vault_path=settings.resolved_vault_path, cwd=Path.cwd()),
         enable_write_tools=os.environ.get("AILSS_ENABLE_WRITE_TOOLS", "").strip() == "1",
-        default_top_k=max(1, min(default_top_k, 50)),
+        default_top_k=max(1, min(default_top_k, 20)),
         shutdown_token=shutdown_token,
     )
 

apps/api/src/ailss_api/mcp_runtime_context_tools.py

@@ -31,8 +31,8 @@ def get_context(
         path_prefix: str | None = None,
         tags_any: list[str] | None = None,
         tags_all: list[str] | None = None,
-        top_k: Annotated[int, Field(ge=1, le=50)] = runtime.default_top_k,
-        expand_top_k: Annotated[int, Field(ge=0, le=50)] = 5,
+        top_k: Annotated[int, Field(ge=1, le=20)] = runtime.default_top_k,
+        expand_top_k: Annotated[int, Field(ge=0, le=20)] = 5,
         hit_chunks_per_note: Annotated[int, Field(ge=1, le=5)] = 2,
         neighbor_window: Annotated[int, Field(ge=0, le=3)] = 1,
         max_evidence_chars_per_note: Annotated[int, Field(ge=200, le=20_000)] = 1500,
@@ -74,6 +74,7 @@ def run() -> dict[str, object]:
                 runtime.settings,
             )
             results = response.results[:top_k]
+            expanded_result_count = min(max(0, expand_top_k), len(results))
             return {
                 "query": query,
                 "top_k": top_k,
@@ -85,7 +86,7 @@ def run() -> dict[str, object]:
                     "tags_all": normalized_tags_all,
                 },
                 "params": {
-                    "expand_top_k": min(max(0, expand_top_k), top_k),
+                    "expand_top_k": expanded_result_count,
                     "hit_chunks_per_note": hit_chunks_per_note,
                     "neighbor_window": neighbor_window,
                     "max_evidence_chars_per_note": max_evidence_chars_per_note,
@@ -103,23 +104,33 @@ def run() -> dict[str, object]:
                         "heading": item.heading,
                         "heading_path": item.heading_path,
                         "snippet": item.snippet,
-                        "evidence_text": item.evidence_text,
-                        "evidence_truncated": item.evidence_truncated,
-                        "evidence_chunks": [
-                            {
-                                "chunk_id": chunk.chunk_id,
-                                "chunk_index": chunk.chunk_index or 0,
-                                "kind": chunk.kind if chunk.kind in {"hit", "neighbor"} else "hit",
-                                "distance": chunk.distance,
-                                "heading": chunk.heading,
-                                "heading_path": chunk.heading_path,
-                            }
-                            for chunk in item.evidence
-                        ],
+                        "evidence_text": item.evidence_text
+                        if index < expanded_result_count
+                        else None,
+                        "evidence_truncated": (
+                            item.evidence_truncated if index < expanded_result_count else False
+                        ),
+                        "evidence_chunks": (
+                            [
+                                {
+                                    "chunk_id": chunk.chunk_id,
+                                    "chunk_index": chunk.chunk_index or 0,
+                                    "kind": (
+                                        chunk.kind if chunk.kind in {"hit", "neighbor"} else "hit"
+                                    ),
+                                    "distance": chunk.distance,
+                                    "heading": chunk.heading,
+                                    "heading_path": chunk.heading_path,
+                                }
+                                for chunk in item.evidence
+                            ]
+                            if index < expanded_result_count
+                            else []
+                        ),
                         "preview": item.preview,
                         "preview_truncated": item.preview_truncated,
                     }
-                    for item in results
+                    for index, item in enumerate(results)
                 ],
             }
 

apps/api/tests/test_mcp_runtime.py

@@ -5,6 +5,7 @@
 from pathlib import Path
 from typing import Any, cast
 
+import pytest
 from mcp.server.fastmcp import FastMCP
 from openai import OpenAI
 from pytest import MonkeyPatch
@@ -320,13 +321,26 @@ def test_mcp_runtime_read_tools_use_python_index_and_vault(
             path_prefix="docs/",
             tags_any=["project"],
             top_k=2,
+            expand_top_k=1,
         )
         results = cast(list[dict[str, object]], context["results"])
+        params = cast(dict[str, object], context["params"])
         assert len(results) == 2
         assert {cast(str, item["path"]) for item in results} == {
             "docs/Child.md",
             "docs/Parent.md",
         }
+        assert params["expand_top_k"] == 1
+        assert sum(1 for item in results if item["evidence_text"] is not None) == 1
+        assert sum(1 for item in results if item["evidence_chunks"]) == 1
+
+        with pytest.raises(Exception, match="less than or equal to 20"):
+            _call_tool(
+                harness.server,
+                "get_context",
+                query="child dependency",
+                top_k=21,
+            )
     finally:
         harness.close()
 

docs/01-overview.md

@@ -35,7 +35,7 @@ Example tools:
 Read-first tools (implemented in this repo):
 
 - `get_context`: semantic retrieval for a query → returns top matching notes (deduped by path) with note metadata and stitched evidence chunks
-  - Default `top_k` can be set via `AILSS_GET_CONTEXT_DEFAULT_TOP_K` (applies only when the caller omits `top_k`; clamped to 1–50; default: 10)
+  - Default `top_k` can be set via `AILSS_GET_CONTEXT_DEFAULT_TOP_K` (applies only when the caller omits `top_k`; clamped to 1–20; default: 10)
   - Returns note metadata + stitched evidence chunks by default (file-start previews are disabled unless explicitly enabled)
   - Default `max_chars_per_note` is 800 (applies only when the caller omits it; clamped to 200–50,000; used for file-start previews when enabled)
   - Optional scoped candidate filters are available: `path_prefix` (literal path prefix), `tags_any`, `tags_all`

docs/ops/local-dev.md

@@ -80,7 +80,7 @@ Notes:
 Optional:
 
 - `AILSS_ENABLE_WRITE_TOOLS=1` (enables explicit write tools like `edit_note`)
-- `AILSS_GET_CONTEXT_DEFAULT_TOP_K=<n>` (sets the default `get_context.top_k` when the caller omits `top_k`; clamped to 1–50; default: 10)
+- `AILSS_GET_CONTEXT_DEFAULT_TOP_K=<n>` (sets the default `get_context.top_k` when the caller omits `top_k`; clamped to 1–20; default: 10)
 
 ## 5) Run Python backend (FastAPI)
 

docs/reference/mcp-tools.md

@@ -14,8 +14,8 @@ Source of truth: `apps/api/src/ailss_api/mcp_runtime.py`.
   - `path_prefix` (string, optional) — literal vault-relative prefix match for candidate notes (not SQL wildcard semantics)
   - `tags_any` (string[], default: `[]`) — candidate notes must include at least one tag
   - `tags_all` (string[], default: `[]`) — candidate notes must include all tags
-  - `top_k` (int, default: `10`, range: `1–50`)
-  - `expand_top_k` (int, default: `5`, range: `0–50`) — how many of the top_k notes include stitched evidence text
+  - `top_k` (int, default: `10`, range: `1–20`)
+  - `expand_top_k` (int, default: `5`, range: `0–20`) — how many of the top_k notes include stitched evidence text
   - `hit_chunks_per_note` (int, default: `2`, range: `1–5`)
   - `neighbor_window` (int, default: `1`, range: `0–3`) — stitches ±window around the best hit
   - `max_evidence_chars_per_note` (int, default: `1500`, range: `200–20,000`)

packages/obsidian-plugin/src/settingsSections/openAiSection.ts

@@ -48,7 +48,7 @@ export function renderOpenAiSection(
 
 	new Setting(containerEl)
 		.setName("Top K")
-		.setDesc("Default get_context.top_k when the caller omits top_k (1–50).")
+		.setDesc("Default get_context.top_k when the caller omits top_k (1–20).")
 		.addText((text) => {
 			text.setPlaceholder("10");
 			text.setValue(String(plugin.settings.topK));

packages/obsidian-plugin/src/utils/clamp.ts

@@ -8,7 +8,7 @@ function clampTopKWithMax(input: number, max: number): number {
 }
 
 export function clampTopK(input: number): number {
-	return clampTopKWithMax(input, 50);
+	return clampTopKWithMax(input, 20);
 }
 
 export function clampPythonApiDefaultTopK(input: number): number {

packages/obsidian-plugin/test/mcp/mcpHttpServiceController.startupHelpers.test.ts

@@ -191,9 +191,9 @@ describe("McpHttpServiceController startup helper unit branches", () => {
 				asInternals(controller).normalizeStartupSettings(settings),
 			).resolves.toEqual({
 				port: 31415,
-				topK: 50,
+				topK: 20,
 			});
-			expect(settings.topK).toBe(50);
+			expect(settings.topK).toBe(20);
 			expect(saveSettings).toHaveBeenCalledTimes(1);
 		});
 

packages/obsidian-plugin/test/utils/clamp.test.ts

@@ -1,12 +1,17 @@
 import { describe, expect, it } from "vitest";
 
 import {
+	clampTopK,
 	clampPythonApiAgentTopK,
 	clampPythonApiDefaultTopK,
 	clampPythonApiPort,
 } from "../../src/utils/clamp.js";
 
 describe("Python clamp helpers", () => {
+	it("caps MCP retrieval defaults at the retrieval maximum", () => {
+		expect(clampTopK(80)).toBe(20);
+	});
+
 	it("uses the Python backend fallback port", () => {
 		expect(clampPythonApiPort(70000)).toBe(8787);
 	});