Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

feat(mcp): add code_outline / code_search / code_expand tools (#2146)

AutoCoder9a37e753953e
diff --git a/docs/design/2026-05-20-code-tools-design.md b/docs/design/2026-05-20-code-tools-design.md
new file mode 100644
index 000000000..27e5f1ade
--- /dev/null
+++ b/docs/design/2026-05-20-code-tools-design.md
@@ -0,0 +1,293 @@
+# Code Tools MCP 集成设计文档
+
+**日期**:2026-05-20
+**范围**:向 OpenViking 新增 `code_outline`、`code_search`、`code_expand` 三个 MCP 工具
+
+---
+
+## 概述
+
+三个新 MCP 工具通过 OpenViking 现有的 `@mcp.tool()` 端点向 AI Agent 暴露代码结构导航能力。典型使用顺序:
+
+```
+code_outline → 查看文件符号结构
+code_search → 跨目录查找符号位置
+code_expand → 展开完整实现代码
+```
+
+**仅支持 `viking://` URI**(不支持直接本地路径),与现有 `read`、`grep`、`list` 等工具保持一致,符合服务端既有安全边界(参见 `local_input_guard.py`:HTTP MCP 端拒绝直接的本地文件系统路径)。需要分析本地代码时,先用 `add_resource` 入库为 `viking://` 资源即可。
+
+---
+
+## 架构
+
+```
+mcp_endpoint.py
+ ├── code_outline(uri) → openviking.parse.parsers.code.ast
+ ├── code_search(query, uri) → openviking.parse.parsers.code.ast
+ └── code_expand(uri, symbol) → openviking.parse.parsers.code.ast
+
+openviking/parse/parsers/code/ast/
+ ├── skeleton.py (修改:给 FunctionSig、ClassSkeleton 加行号字段)
+ ├── extractor.py (修改:新增 extract() 返回 CodeSkeleton,extract_skeleton 复用之)
+ ├── code_tools.py (新增:outline_file、search_symbols、expand_symbol)
+ └── languages/
+ ├── python.py (修改:读取 node.start_point / end_point)
+ ├── js_ts.py (修改)
+ ├── go.py (修改)
+ ├── rust.py (修改)
+ ├── java.py (修改)
+ ├── cpp.py (修改:3 处函数提取路径都要改)
+ └── ...
+```
+
+无新增依赖,使用已安装的 `tree-sitter` Python 绑定。
+
+---
+
+## 各组件改动说明
+
+### 1. `skeleton.py` — 新增行号字段
+
+给 `FunctionSig` 和 `ClassSkeleton` 加 `line_start`、`line_end`:
+
+```python
+@dataclass
+class FunctionSig:
+ name: str
+ params: str
+ return_type: str
+ docstring: str
+ line_start: int = 0 # 1-indexed,起始行(含)
+ line_end: int = 0 # 1-indexed,结束行(含)
+
+@dataclass
+class ClassSkeleton:
+ name: str
+ bases: List[str]
+ docstring: str
+ methods: List[FunctionSig] = field(default_factory=list)
+ line_start: int = 0
+ line_end: int = 0
+```
+
+默认值 `0` 保持向后兼容,现有调用方(`extract_skeleton`、嵌入流水线)无需改动。
+
+`to_text()` **不改**——它服务于 embedding/LLM 输入场景,行号会污染那条路径。outline 的展示由 `code_tools.outline_file()` 独立实现。
+
+### 2. `extractor.py` — 新增 `extract()` 返回 `CodeSkeleton`
+
+现有 `ASTExtractor.extract_skeleton()` 返回的是格式化文本字符串,不是 `CodeSkeleton` 对象。代码工具需要原始结构,因此在 `ASTExtractor` 上新增公开方法:
+
+```python
+def extract(self, file_name: str, content: str) -> Optional[CodeSkeleton]:
+ """Return raw CodeSkeleton or None for unsupported/failed extraction."""
+ lang = self._detect_language(file_name)
+ extractor = self._get_extractor(lang)
+ if extractor is None:
+ return None
+ try:
+ return extractor.extract(file_name, content)
+ except Exception as e:
+ logger.warning(
+ "AST extraction failed for '%s' (language: %s): %s", file_name, lang, e
+ )
+ return None
+```
+
+`extract_skeleton()` 重构为先调 `extract()`、再 `.to_text(verbose)`,逻辑完全等价。
+
+### 3. 各语言提取器 — 读取节点行号
+
+每个 `_extract_function` / `_extract_class` / `_extract_struct` 在构造 `FunctionSig` / `ClassSkeleton` 时多传两个参数:
+
+```python
+# tree-sitter node.start_point = (row, col),0-indexed
+line_start = node.start_point[0] + 1
+line_end = node.end_point[0] + 1
+```
+
+**特别注意 `cpp.py`**:该文件有三处函数构造路径——`_extract_function_declarator`、`_extract_function`、`_extract_function_proto`——三处都要传行号。其他语言每个文件改 2 处(函数 + 类/struct)即可。
+
+### 4. `code_tools.py` — 新增模块
+
+新建 `openviking/parse/parsers/code/ast/code_tools.py`,三个纯函数,无 I/O 无异步,输入字符串、返回格式化字符串。I/O 与逻辑分离便于独立测试。
+
+```python
+def outline_file(content: str, file_name: str) -> str:
+ """返回源文件的符号结构(含行号、总行数)。
+ 内部:ASTExtractor.extract() -> CodeSkeleton -> 专用 outline 格式器。"""
+
+def search_symbols(query: str, files: list[tuple[str, str]]) -> str:
+ """在多个 (content, file_name) 中搜索符号名包含 query 的符号
+ (大小写不敏感子串匹配)。"""
+
+def expand_symbol(content: str, file_name: str, symbol: str) -> str:
+ """返回符号完整源码。symbol 支持两种形式:
+ - 'foo' 匹配任意位置同名函数/类/方法
+ - 'Foo.bar' 精确匹配 Foo 类下的 bar 方法
+ 同名多个返回第一个;区分大小写。"""
+```
+
+### 5. `mcp_endpoint.py` — 新增三个工具
+
+```python
+async def code_outline(uri: str) -> str:
+ """展示源文件的符号结构——类、函数、方法及其行号范围。
+ uri 必须是 viking:// URI。"""
+
+async def code_search(query: str, uri: str) -> str:
+ """在 viking:// 目录下按名称搜索符号。query 对符号名做大小写不敏感
+ 子串匹配,返回匹配符号及其文件位置和行号。最多扫描 200 个文件。
+ uri 必填——不提供默认值以避免误扫整个 VikingFS。"""
+
+async def code_expand(uri: str, symbol: str) -> str:
+ """返回源文件中指定符号(函数、类或方法)的完整源码。
+ symbol 支持 'bar' 和 'Foo.bar' 两种形式。"""
+```
+
+---
+
+## URI 解析
+
+仅处理 `viking://` URI,通过 `service.fs` 调用:
+
+```
+viking://resources/owner/repo/src/auth.py
+ → service.fs.read(uri, ctx=ctx) # 文件内容
+
+viking://resources/owner/repo/src/
+ → service.fs.ls(uri, ctx=ctx, recursive=True, output="original")
+ 返回 dict 列表,字段:name、isDir、uri(camelCase)
+```
+
+辅助函数 `_resolve_code_dir(uri, service, ctx)` 完成 ls + 按扩展名过滤 + 并发读取。
+
+支持的扩展名(与 `extractor._EXT_MAP` 对齐):
+`.py .js .jsx .ts .tsx .java .c .cpp .cc .h .hpp .rs .go .cs .php .lua`
+
+---
+
+## 数据流
+
+### `code_outline(uri)`
+
+```
+uri
+ → service.fs.read() → content
+ → ASTExtractor.extract() → CodeSkeleton(或 None)
+ → outline_file() → 格式化字符串
+```
+
+None 时直接返回 `"不支持的语言:{file_name}"` 或 `"解析 {file_name} 失败"`。
+
+### `code_search(query, uri)`
+
+```
+uri(目录)
+ → service.fs.ls(recursive=True, output="original")
+ → 按扩展名过滤,截断到 200 个 → list[uri]
+ → asyncio.gather + Semaphore(10) 并发 service.fs.read()
+ → list[(content, file_name)]
+ → 逐文件 ASTExtractor.extract() → list[CodeSkeleton]
+ → search_symbols(query, ...) → 格式化字符串
+```
+
+并发模式参考已有 `read` 工具(`mcp_endpoint.py:290`)。解析失败的文件跳过、记录 warning,不中断整体搜索。
+
+### `code_expand(uri, symbol)`
+
+```
+uri
+ → service.fs.read() → content
+ → ASTExtractor.extract() → CodeSkeleton
+ → expand_symbol() → content 的 [line_start-1 : line_end] 行 + 位置标注
+```
+
+---
+
+## 输出格式
+
+### `code_outline`
+
+`outline_file()` 不复用 `CodeSkeleton.to_text()`(那是嵌入流水线格式),自带格式器:
+
+```
+auth.py [Python, 120 lines]
+
+imports: os, typing.Optional, fastapi.HTTPException
+
+class AuthHandler L18-62
+ + __init__(self, secret: str) L20-25
+ + authenticate(self, token: str) -> Optional[User] L27-45
+ + verify_scope(self, user: User, scope: str) -> bool L47-60
+
+def get_handler() -> AuthHandler L65-70
+```
+
+- 头部行的语言名直接用 `CodeSkeleton.language`(Python/JavaScript/TypeScript 等,保留 `extractor` 已有 casing)
+- 总行数由 `outline_file()` 内 `content.count("\n") + 1` 计算
+- 不输出 docstring,行号是导航主信息
+
+### `code_search`
+
+```
+2 matches for "authenticate" (scanned 47 files)
+
+src/auth.py
+ AuthHandler.authenticate L27-45
+ authenticate_request L75-88
+```
+
+如果到达 200 文件上限,输出末尾追加 `(scanning stopped at 200-file cap; narrow uri to search more)`。
+
+### `code_expand`
+
+```
+# src/auth.py L27-45
+
+def authenticate(self, token: str) -> Optional[User]:
+ payload = jwt.decode(token, self.secret)
+ user_id = payload.get("sub")
+ if not user_id:
+ raise HTTPException(status_code=401)
+ return db.get(User, user_id)
+```
+
+---
+
+## 错误处理
+
+| 场景 | 工具 | 返回内容 |
+|------|------|---------|
+| 不支持的语言(扩展名不在 `_EXT_MAP`) | outline / expand | `"不支持的语言:{file_name}"` |
+| 不支持的语言 | search | 静默跳过该文件 |
+| 解析失败 | outline / expand | `"解析 {file_name} 失败:{reason}"`(明确错误,**不** "继续") |
+| 解析失败 | search | 记录 warning,跳过该文件,继续 |
+| 符号未找到 | expand | `"在 {file_name} 中未找到符号 '{symbol}'"` |
+| URI 不存在 | 全部 | 透传 `AGFSNotFoundError` 或 `FileNotFoundError` |
+| 目录为空 / 无可解析文件 | search | `"在 {uri} 中未找到支持的源文件"` |
+| 传入非 viking:// URI | 全部 | `"仅支持 viking:// URI;本地路径请先 add_resource"` |
+
+---
+
+## 涉及文件清单
+
+| 文件 | 改动类型 |
+|------|---------|
+| `openviking/parse/parsers/code/ast/skeleton.py` | 新增 `line_start`、`line_end` 字段(默认 0) |
+| `openviking/parse/parsers/code/ast/extractor.py` | 新增 `extract()` 返回 `CodeSkeleton`;`extract_skeleton` 重构复用之 |
+| `openviking/parse/parsers/code/ast/languages/python.py` | 读取节点行号(2 处) |
+| `openviking/parse/parsers/code/ast/languages/js_ts.py` | 读取节点行号(2 处) |
+| `openviking/parse/parsers/code/ast/languages/go.py` | 读取节点行号(2 处:function、struct) |
+| `openviking/parse/parsers/code/ast/languages/rust.py` | 读取节点行号(2 处) |
+| `openviking/parse/parsers/code/ast/languages/java.py` | 读取节点行号(2 处) |
+| `openviking/parse/parsers/code/ast/languages/cpp.py` | 读取节点行号(**3 处**:declarator、function、proto) |
+| `openviking/parse/parsers/code/ast/languages/csharp.py` | 读取节点行号(2 处) |
+| `openviking/parse/parsers/code/ast/languages/php.py` | 读取节点行号(2 处) |
+| `openviking/parse/parsers/code/ast/languages/lua.py` | 读取节点行号(2 处) |
+| `openviking/parse/parsers/code/ast/code_tools.py` | **新增文件** |
+| `openviking/server/mcp_endpoint.py` | 新增 3 个工具 + viking:// 校验辅助 |
diff --git a/openviking/parse/parsers/code/ast/code_tools.py b/openviking/parse/parsers/code/ast/code_tools.py
new file mode 100644
index 000000000..4873b8623
--- /dev/null
+++ b/openviking/parse/parsers/code/ast/code_tools.py
@@ -0,0 +1,183 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+"""Pure I/O-free formatters powering the code_outline / code_search / code_expand
+MCP tools. Inputs are source strings; outputs are agent-facing text.
+
+The MCP layer handles all URI resolution and I/O; this module deals only with
+content -> CodeSkeleton -> formatted text.
+"""
+
+from __future__ import annotations
+
+from typing import Iterable, List, Optional, Tuple
+
+from openviking.parse.parsers.code.ast.extractor import get_extractor
+from openviking.parse.parsers.code.ast.skeleton import (
+ CodeSkeleton,
+ FunctionSig,
+ _compact_params,
+)
+
+
+def _line_span(item) -> str:
+ if item.line_start and item.line_end:
+ return f" L{item.line_start}-{item.line_end}"
+ return ""
+
+
+def _format_function(fn: FunctionSig, indent: str, prefix: str) -> str:
+ ret = f" -> {fn.return_type}" if fn.return_type else ""
+ params = _compact_params(fn.params)
+ return f"{indent}{prefix}{fn.name}({params}){ret}{_line_span(fn)}"
+
+
+def _outline_text(skeleton: CodeSkeleton, total_lines: int) -> str:
+ lines: List[str] = [f"{skeleton.file_name} [{skeleton.language}, {total_lines} lines]"]
+ if skeleton.module_doc:
+ first = skeleton.module_doc.split("\n", 1)[0].strip()
+ if first:
+ lines.append(f'module: "{first}"')
+ if skeleton.imports:
+ lines.append(f"imports: {', '.join(skeleton.imports)}")
+ lines.append("")
+
+ for cls in skeleton.classes:
+ bases = f"({', '.join(cls.bases)})" if cls.bases else ""
+ lines.append(f"class {cls.name}{bases}{_line_span(cls)}")
+ for method in cls.methods:
+ lines.append(_format_function(method, " ", "+ "))
+ lines.append("")
+
+ for fn in skeleton.functions:
+ lines.append(_format_function(fn, "", "def "))
+
+ return "\n".join(lines).rstrip()
+
+
+def outline_file(content: str, file_name: str) -> str:
+ """Return outline view of one source file (header + symbols + line spans).
+
+ Returns an "Error: ..." sentinel string when the language is unsupported or
+ parsing fails — callers can detect by the "Error:" prefix.
+ """
+ skeleton = get_extractor().extract(file_name, content)
+ if skeleton is None:
+ return _failure_message(file_name)
+ total_lines = content.count("\n") + 1 if content else 0
+ return _outline_text(skeleton, total_lines)
+
+
+def _failure_message(file_name: str) -> str:
+ if not get_extractor().supports(file_name):
+ return f"Error: unsupported language for {file_name}"
+ return f"Error: failed to parse {file_name}"
+
+
+def _iter_symbols(skeleton: CodeSkeleton) -> Iterable[Tuple[str, int, int]]:
+ """Yield (display_name, line_start, line_end) for every symbol."""
+ for cls in skeleton.classes:
+ yield cls.name, cls.line_start, cls.line_end
+ for method in cls.methods:
+ yield f"{cls.name}.{method.name}", method.line_start, method.line_end
+ for fn in skeleton.functions:
+ yield fn.name, fn.line_start, fn.line_end
+
+
+def search_symbols(query: str, files: List[Tuple[str, str]]) -> str:
+ """Case-insensitive substring search across symbol names in many files.
+
+ files: list of (content, file_name) tuples. Files whose language is
+ unsupported or fails to parse are silently skipped (the caller already
+ filtered by extension).
+ """
+ if not query:
+ return "Error: empty query"
+
+ needle = query.lower()
+ extractor = get_extractor()
+ scanned = 0
+ hits_by_file: List[Tuple[str, List[Tuple[str, int, int]]]] = []
+ total = 0
+
+ for content, file_name in files:
+ scanned += 1
+ skeleton = extractor.extract(file_name, content)
+ if skeleton is None:
+ continue
+ file_hits: List[Tuple[str, int, int]] = []
+ for name, start, end in _iter_symbols(skeleton):
+ tail = name.rsplit(".", 1)[-1]
+ haystack = name.lower() if "." in needle else tail.lower()
+ if needle in haystack:
+ file_hits.append((name, start, end))
+ if file_hits:
+ hits_by_file.append((file_name, file_hits))
+ total += len(file_hits)
+
+ if total == 0:
+ return f'No matches for "{query}" (scanned {scanned} files)'
+
+ out: List[str] = [f'{total} matches for "{query}" (scanned {scanned} files)']
+ for file_name, file_hits in hits_by_file:
+ out.append("")
+ out.append(file_name)
+ for name, start, end in file_hits:
+ span = f" L{start}-{end}" if start and end else ""
+ out.append(f" {name}{span}")
+ return "\n".join(out)
+
+
+def _resolve_symbol(
+ skeleton: CodeSkeleton, symbol: str
+) -> Optional[Tuple[str, int, int]]:
+ """Find a symbol by 'foo' (bare) or 'Foo.bar' (qualified). Case sensitive.
+
+ Search priority for bare names (no dot):
+ 1. Top-level functions — exact name match
+ 2. Classes — exact name match
+ 3. Methods in any class — bare method name, first class that contains it wins
+ (returns qualified display name "ClassName.method" so the caller knows
+ where the method lives; use 'Foo.bar' to target a specific class)
+ """
+ if "." in symbol:
+ cls_name, method_name = symbol.split(".", 1)
+ for cls in skeleton.classes:
+ if cls.name == cls_name:
+ for method in cls.methods:
+ if method.name == method_name:
+ return f"{cls.name}.{method.name}", method.line_start, method.line_end
+ return None
+
+ for fn in skeleton.functions:
+ if fn.name == symbol:
+ return fn.name, fn.line_start, fn.line_end
+ for cls in skeleton.classes:
+ if cls.name == symbol:
+ return cls.name, cls.line_start, cls.line_end
+ for method in cls.methods:
+ if method.name == symbol:
+ return f"{cls.name}.{method.name}", method.line_start, method.line_end
+ return None
+
+
+def expand_symbol(content: str, file_name: str, symbol: str) -> str:
+ """Return the source for `symbol` from `content`, with a location header.
+
+ Accepts 'foo' (any function/class/method named foo, first match wins) or
+ 'Foo.bar' (method bar inside class Foo).
+ """
+ skeleton = get_extractor().extract(file_name, content)
+ if skeleton is None:
+ return _failure_message(file_name)
+
+ match = _resolve_symbol(skeleton, symbol)
+ if match is None:
+ return f"Error: symbol '{symbol}' not found in {file_name}"
+
+ display_name, start, end = match
+ if not start or not end:
+ return f"Error: symbol '{symbol}' found but line numbers unavailable in {file_name}"
+
+ lines = content.splitlines()
+ body = "\n".join(lines[start - 1 : end])
+ return f"# {file_name} L{start}-{end} ({display_name})\n\n{body}"
diff --git a/openviking/parse/parsers/code/ast/extractor.py b/openviking/parse/parsers/code/ast/extractor.py
index e737cf02c..fee68b992 100644
--- a/openviking/parse/parsers/code/ast/extractor.py
+++ b/openviking/parse/parsers/code/ast/extractor.py
@@ -89,17 +89,15 @@ class ASTExtractor:
self._cache[lang] = None
return None
- def extract_skeleton(
- self, file_name: str, content: str, verbose: bool = False
- ) -> Optional[str]:
- """Extract skeleton text from source code.
+ def supports(self, file_name: str) -> bool:
+ """True if the file extension maps to a known language (parsing may still fail)."""
+ return self._detect_language(file_name) is not None
- Returns None for unsupported languages or on extraction failure,
- signalling the caller to fall back to LLM.
+ def extract(self, file_name: str, content: str) -> Optional[CodeSkeleton]:
+ """Return raw CodeSkeleton, or None for unsupported language / parse failure.
- Args:
- verbose: If True, include full docstrings (for ast_llm / LLM input).
- If False, only first line of each docstring (for ast / embedding).
+ Consumers that need the structured object (line numbers, traversal) call
+ this; consumers that want the legacy formatted text use extract_skeleton.
"""
lang = self._detect_language(file_name)
extractor = self._get_extractor(lang)
@@ -107,17 +105,30 @@ class ASTExtractor:
return None
try:
- skeleton: CodeSkeleton = extractor.extract(file_name, content)
- return skeleton.to_text(verbose=verbose)
+ return extractor.extract(file_name, content)
except Exception as e:
logger.warning(
- "AST extraction failed for '%s' (language: %s), falling back to LLM: %s",
- file_name,
- lang,
- e,
+ "AST extraction failed for '%s' (language: %s): %s", file_name, lang, e
)
return None
+ def extract_skeleton(
+ self, file_name: str, content: str, verbose: bool = False
+ ) -> Optional[str]:
+ """Extract skeleton text from source code.
+
+ Returns None for unsupported languages or on extraction failure,
+ signalling the caller to fall back to LLM.
+
+ Args:
+ verbose: If True, include full docstrings (for ast_llm / LLM input).
+ If False, only first line of each docstring (for ast / embedding).
+ """
+ skeleton = self.extract(file_name, content)
+ if skeleton is None:
+ return None
+ return skeleton.to_text(verbose=verbose)
+
# Module-level singleton
_extractor: Optional[ASTExtractor] = None
diff --git a/openviking/parse/parsers/code/ast/languages/cpp.py b/openviking/parse/parsers/code/ast/languages/cpp.py
index cb4a4bd2e..f548df9d6 100644
--- a/openviking/parse/parsers/code/ast/languages/cpp.py
+++ b/openviking/parse/parsers/code/ast/languages/cpp.py
@@ -79,7 +79,14 @@ def _extract_function(node, content_bytes: bytes, docstring: str = "") -> Functi
if sub.type == "function_declarator":
name, params = _extract_function_declarator(sub, content_bytes)
- return FunctionSig(name=name, params=params, return_type=return_type, docstring=docstring)
+ return FunctionSig(
+ name=name,
+ params=params,
+ return_type=return_type,
+ docstring=docstring,
+ line_start=node.start_point[0] + 1,
+ line_end=node.end_point[0] + 1,
+ )
def _extract_class(node, content_bytes: bytes, docstring: str = "") -> ClassSkeleton:
@@ -127,11 +134,23 @@ def _extract_class(node, content_bytes: bytes, docstring: str = "") -> ClassSkel
doc = _preceding_doc(siblings, idx, content_bytes)
methods.append(
FunctionSig(
- name=fn_name, params=fn_params, return_type=ret_type, docstring=doc
+ name=fn_name,
+ params=fn_params,
+ return_type=ret_type,
+ docstring=doc,
+ line_start=child.start_point[0] + 1,
+ line_end=child.end_point[0] + 1,
)
)
- return ClassSkeleton(name=name, bases=bases, docstring=docstring, methods=methods)
+ return ClassSkeleton(
+ name=name,
+ bases=bases,
+ docstring=docstring,
+ methods=methods,
+ line_start=node.start_point[0] + 1,
+ line_end=node.end_point[0] + 1,
+ )
def _extract_typedef_struct(
@@ -155,9 +174,11 @@ def _extract_typedef_struct(
return None
skeleton = _extract_class(struct_node, content_bytes, docstring=docstring)
- # Prefer the typedef alias as the canonical name
+ # Prefer the typedef alias as the canonical name; span the outer typedef.
if typedef_name:
skeleton.name = typedef_name
+ skeleton.line_start = node.start_point[0] + 1
+ skeleton.line_end = node.end_point[0] + 1
return skeleton if skeleton.name else None
diff --git a/openviking/parse/parsers/code/ast/languages/csharp.py b/openviking/parse/parsers/code/ast/languages/csharp.py
index 7394e62e0..7c626a778 100644
--- a/openviking/parse/parsers/code/ast/languages/csharp.py
+++ b/openviking/parse/parsers/code/ast/languages/csharp.py
@@ -98,7 +98,14 @@ def _extract_method(node, content_bytes: bytes, docstring: str = "") -> Function
if accessors:
params = f"{{ {' '.join(accessors)} }}"
- return FunctionSig(name=name, params=params, return_type=return_type, docstring=docstring)
+ return FunctionSig(
+ name=name,
+ params=params,
+ return_type=return_type,
+ docstring=docstring,
+ line_start=node.start_point[0] + 1,
+ line_end=node.end_point[0] + 1,
+ )
def _extract_class(node, content_bytes: bytes, docstring: str = "") -> ClassSkeleton:
@@ -127,7 +134,14 @@ def _extract_class(node, content_bytes: bytes, docstring: str = "") -> ClassSkel
doc = _preceding_doc(siblings, idx, content_bytes)
methods.append(_extract_method(child, content_bytes, docstring=doc))
- return ClassSkeleton(name=name, bases=bases, docstring=docstring, methods=methods)
+ return ClassSkeleton(
+ name=name,
+ bases=bases,
+ docstring=docstring,
+ methods=methods,
+ line_start=node.start_point[0] + 1,
+ line_end=node.end_point[0] + 1,
+ )
class CSharpExtractor(LanguageExtractor):
diff --git a/openviking/parse/parsers/code/ast/languages/go.py b/openviking/parse/parsers/code/ast/languages/go.py
index 7a61a2ea5..1f793d0fc 100644
--- a/openviking/parse/parsers/code/ast/languages/go.py
+++ b/openviking/parse/parsers/code/ast/languages/go.py
@@ -50,7 +50,14 @@ def _extract_function(node, content_bytes: bytes, docstring: str = "") -> Functi
elif child.type == "type_identifier":
return_type = _node_text(child, content_bytes)
- return FunctionSig(name=name, params=params, return_type=return_type, docstring=docstring)
+ return FunctionSig(
+ name=name,
+ params=params,
+ return_type=return_type,
+ docstring=docstring,
+ line_start=node.start_point[0] + 1,
+ line_end=node.end_point[0] + 1,
+ )
def _extract_struct(node, content_bytes: bytes, docstring: str = "") -> ClassSkeleton:
@@ -59,7 +66,14 @@ def _extract_struct(node, content_bytes: bytes, docstring: str = "") -> ClassSke
if child.type == "type_identifier":
name = _node_text(child, content_bytes)
break
- return ClassSkeleton(name=name, bases=[], docstring=docstring, methods=[])
+ return ClassSkeleton(
+ name=name,
+ bases=[],
+ docstring=docstring,
+ methods=[],
+ line_start=node.start_point[0] + 1,
+ line_end=node.end_point[0] + 1,
+ )
class GoExtractor(LanguageExtractor):
diff --git a/openviking/parse/parsers/code/ast/languages/java.py b/openviking/parse/parsers/code/ast/languages/java.py
index eec544be5..91a1e93ab 100644
--- a/openviking/parse/parsers/code/ast/languages/java.py
+++ b/openviking/parse/parsers/code/ast/languages/java.py
@@ -61,7 +61,14 @@ def _extract_method(node, content_bytes: bytes, docstring: str = "") -> Function
raw = raw[1:-1]
params = raw.strip()
- return FunctionSig(name=name, params=params, return_type=return_type, docstring=docstring)
+ return FunctionSig(
+ name=name,
+ params=params,
+ return_type=return_type,
+ docstring=docstring,
+ line_start=node.start_point[0] + 1,
+ line_end=node.end_point[0] + 1,
+ )
def _extract_class(node, content_bytes: bytes, docstring: str = "") -> ClassSkeleton:
@@ -93,7 +100,14 @@ def _extract_class(node, content_bytes: bytes, docstring: str = "") -> ClassSkel
doc = _preceding_doc(siblings, idx, content_bytes)
methods.append(_extract_method(child, content_bytes, docstring=doc))
- return ClassSkeleton(name=name, bases=bases, docstring=docstring, methods=methods)
+ return ClassSkeleton(
+ name=name,
+ bases=bases,
+ docstring=docstring,
+ methods=methods,
+ line_start=node.start_point[0] + 1,
+ line_end=node.end_point[0] + 1,
+ )
class JavaExtractor(LanguageExtractor):
diff --git a/openviking/parse/parsers/code/ast/languages/js_ts.py b/openviking/parse/parsers/code/ast/languages/js_ts.py
index 424cc3c08..375ca7449 100644
--- a/openviking/parse/parsers/code/ast/languages/js_ts.py
+++ b/openviking/parse/parsers/code/ast/languages/js_ts.py
@@ -90,7 +90,14 @@ def _extract_function(
if not docstring:
docstring = _first_string_in_body(body_node, content_bytes)
- return FunctionSig(name=name, params=params, return_type=return_type, docstring=docstring)
+ return FunctionSig(
+ name=name,
+ params=params,
+ return_type=return_type,
+ docstring=docstring,
+ line_start=node.start_point[0] + 1,
+ line_end=node.end_point[0] + 1,
+ )
def _extract_class(
@@ -138,7 +145,14 @@ def _extract_class(
methods.append(fn)
break
- return ClassSkeleton(name=name, bases=bases, docstring=docstring, methods=methods)
+ return ClassSkeleton(
+ name=name,
+ bases=bases,
+ docstring=docstring,
+ methods=methods,
+ line_start=node.start_point[0] + 1,
+ line_end=node.end_point[0] + 1,
+ )
class JsTsExtractor(LanguageExtractor):
diff --git a/openviking/parse/parsers/code/ast/languages/lua.py b/openviking/parse/parsers/code/ast/languages/lua.py
index dd1a01b8f..8af37e745 100644
--- a/openviking/parse/parsers/code/ast/languages/lua.py
+++ b/openviking/parse/parsers/code/ast/languages/lua.py
@@ -125,10 +125,19 @@ class LuaExtractor(LanguageExtractor):
params = _extract_params(params_node, content_bytes)
+ fn_start = child.start_point[0] + 1
+ fn_end = child.end_point[0] + 1
if name_node.type == "identifier":
name = _node_text(name_node, content_bytes)
functions.append(
- FunctionSig(name=name, params=params, return_type="", docstring=doc)
+ FunctionSig(
+ name=name,
+ params=params,
+ return_type="",
+ docstring=doc,
+ line_start=fn_start,
+ line_end=fn_end,
+ )
)
elif name_node.type in ("dot_index_expression", "method_index_expression"):
# M.foo or M:foo — map to class method
@@ -137,11 +146,25 @@ class LuaExtractor(LanguageExtractor):
table_name = _node_text(id_children[0], content_bytes)
method_name = _node_text(id_children[1], content_bytes)
fn = FunctionSig(
- name=method_name, params=params, return_type="", docstring=doc
+ name=method_name,
+ params=params,
+ return_type="",
+ docstring=doc,
+ line_start=fn_start,
+ line_end=fn_end,
)
if table_name not in _classes:
_classes[table_name] = ClassSkeleton(
- name=table_name, bases=[], docstring="", methods=[]
+ name=table_name,
+ bases=[],
+ docstring="",
+ methods=[],
+ line_start=fn_start,
+ line_end=fn_end,
+ )
+ else:
+ _classes[table_name].line_end = max(
+ _classes[table_name].line_end, fn_end
)
_classes[table_name].methods.append(fn)
diff --git a/openviking/parse/parsers/code/ast/languages/php.py b/openviking/parse/parsers/code/ast/languages/php.py
index e33e1d3bb..8b9df46d6 100644
--- a/openviking/parse/parsers/code/ast/languages/php.py
+++ b/openviking/parse/parsers/code/ast/languages/php.py
@@ -187,7 +187,14 @@ def _extract_function_like(node, content_bytes: bytes, docstring: str = "") -> F
if return_type:
break
- return FunctionSig(name=name, params=params, return_type=return_type, docstring=docstring)
+ return FunctionSig(
+ name=name,
+ params=params,
+ return_type=return_type,
+ docstring=docstring,
+ line_start=node.start_point[0] + 1,
+ line_end=node.end_point[0] + 1,
+ )
def _extract_class(
@@ -234,7 +241,14 @@ def _extract_class(
doc = _preceding_doc(siblings, idx, content_bytes)
methods.append(_extract_function_like(child, content_bytes, docstring=doc))
- return ClassSkeleton(name=name, bases=bases, docstring=docstring, methods=methods)
+ return ClassSkeleton(
+ name=name,
+ bases=bases,
+ docstring=docstring,
+ methods=methods,
+ line_start=node.start_point[0] + 1,
+ line_end=node.end_point[0] + 1,
+ )
def _dedup_keep_order(items: List[str]) -> List[str]:
diff --git a/openviking/parse/parsers/code/ast/languages/python.py b/openviking/parse/parsers/code/ast/languages/python.py
index af573a6b9..735e0f4ca 100644
--- a/openviking/parse/parsers/code/ast/languages/python.py
+++ b/openviking/parse/parsers/code/ast/languages/python.py
@@ -51,7 +51,14 @@ def _extract_function(node, content_bytes: bytes) -> FunctionSig:
body_node = child
docstring = _first_string_child(body_node, content_bytes)
- return FunctionSig(name=name, params=params, return_type=return_type, docstring=docstring)
+ return FunctionSig(
+ name=name,
+ params=params,
+ return_type=return_type,
+ docstring=docstring,
+ line_start=node.start_point[0] + 1,
+ line_end=node.end_point[0] + 1,
+ )
def _extract_class(node, content_bytes: bytes) -> ClassSkeleton:
@@ -82,7 +89,14 @@ def _extract_class(node, content_bytes: bytes) -> ClassSkeleton:
if sub.type == "function_definition":
methods.append(_extract_function(sub, content_bytes))
- return ClassSkeleton(name=name, bases=bases, docstring=docstring, methods=methods)
+ return ClassSkeleton(
+ name=name,
+ bases=bases,
+ docstring=docstring,
+ methods=methods,
+ line_start=node.start_point[0] + 1,
+ line_end=node.end_point[0] + 1,
+ )
def _extract_imports(node, content_bytes: bytes) -> List[str]:
diff --git a/openviking/parse/parsers/code/ast/languages/rust.py b/openviking/parse/parsers/code/ast/languages/rust.py
index 1dde6b99a..5b6eb6a69 100644
--- a/openviking/parse/parsers/code/ast/languages/rust.py
+++ b/openviking/parse/parsers/code/ast/languages/rust.py
@@ -47,7 +47,14 @@ def _extract_function(node, content_bytes: bytes, docstring: str = "") -> Functi
elif child.type == "generic_type":
return_type = _node_text(child, content_bytes)
- return FunctionSig(name=name, params=params, return_type=return_type, docstring=docstring)
+ return FunctionSig(
+ name=name,
+ params=params,
+ return_type=return_type,
+ docstring=docstring,
+ line_start=node.start_point[0] + 1,
+ line_end=node.end_point[0] + 1,
+ )
def _extract_struct_or_trait(node, content_bytes: bytes, docstring: str = "") -> ClassSkeleton:
@@ -62,7 +69,14 @@ def _extract_struct_or_trait(node, content_bytes: bytes, docstring: str = "") ->
if sub.type == "type_identifier":
bases.append(_node_text(sub, content_bytes))
- return ClassSkeleton(name=name, bases=bases, docstring=docstring, methods=[])
+ return ClassSkeleton(
+ name=name,
+ bases=bases,
+ docstring=docstring,
+ methods=[],
+ line_start=node.start_point[0] + 1,
+ line_end=node.end_point[0] + 1,
+ )
def _extract_impl(node, content_bytes: bytes) -> ClassSkeleton:
@@ -80,7 +94,14 @@ def _extract_impl(node, content_bytes: bytes) -> ClassSkeleton:
doc = _preceding_doc(siblings, idx, content_bytes)
methods.append(_extract_function(sub, content_bytes, docstring=doc))
- return ClassSkeleton(name=f"impl {name}", bases=[], docstring="", methods=methods)
+ return ClassSkeleton(
+ name=f"impl {name}",
+ bases=[],
+ docstring="",
+ methods=methods,
+ line_start=node.start_point[0] + 1,
+ line_end=node.end_point[0] + 1,
+ )
class RustExtractor(LanguageExtractor):
diff --git a/openviking/parse/parsers/code/ast/skeleton.py b/openviking/parse/parsers/code/ast/skeleton.py
index 739e99f1e..260712482 100644
--- a/openviking/parse/parsers/code/ast/skeleton.py
+++ b/openviking/parse/parsers/code/ast/skeleton.py
@@ -18,6 +18,8 @@ class FunctionSig:
params: str # raw parameter string, e.g. "source, instruction, **kwargs"
return_type: str # e.g. "ParseResult" or ""
docstring: str # first line only
+ line_start: int = 0 # 1-indexed, inclusive; 0 = unknown (back-compat)
+ line_end: int = 0 # 1-indexed, inclusive; 0 = unknown
@dataclass
@@ -26,6 +28,8 @@ class ClassSkeleton:
bases: List[str]
docstring: str
methods: List[FunctionSig] = field(default_factory=list)
+ line_start: int = 0
+ line_end: int = 0
@dataclass
diff --git a/openviking/server/mcp_endpoint.py b/openviking/server/mcp_endpoint.py
index f66171f81..1d76b2ff3 100644
--- a/openviking/server/mcp_endpoint.py
+++ b/openviking/server/mcp_endpoint.py
@@ -3,7 +3,8 @@
"""MCP (Model Context Protocol) endpoint for OpenViking server.
Exposes tools to Claude Code (or any MCP client) via streamable HTTP:
- find, search, read, list, remember, add_resource, grep, glob, forget, health
+ find, search, read, list, remember, add_resource, grep, glob,
+ code_outline, code_search, code_expand, forget, health
Mounted on the FastAPI app at /mcp. The MCP session manager lifecycle is
tied to the FastAPI app lifespan (not a sub-app lifespan) so the task group
@@ -15,6 +16,7 @@ are extracted from HTTP request scope and propagated via contextvars.
from __future__ import annotations
+import asyncio
import contextvars
import os
from contextlib import asynccontextmanager
@@ -29,6 +31,12 @@ from starlette.requests import Request
from starlette.responses import JSONResponse
from starlette.types import ASGIApp, Receive, Scope, Send
+from openviking.parse.parsers.code.ast.code_tools import (
+ expand_symbol,
+ outline_file,
+ search_symbols,
+)
+from openviking.parse.parsers.code.ast.extractor import get_extractor
from openviking.server.auth import resolve_identity
from openviking.server.dependencies import get_server_config, get_service
from openviking.server.identity import RequestContext
@@ -784,6 +792,152 @@ async def forget(uri: str, recursive: bool = False) -> str:
return f"Deleted: {uri}"
+# -- code navigation -------------------------------------------------------
+
+_CODE_SEARCH_FILE_CAP = 200
+_CODE_SEARCH_CONCURRENCY = 10
+
+
+def _require_viking_uri(uri: str) -> Optional[str]:
+ """Return error message if uri is not a viking:// URI, else None."""
+ if not isinstance(uri, str) or not uri.startswith("viking://"):
+ return (
+ "Error: only viking:// URIs are supported; "
+ "use add_resource to ingest local code as a viking:// resource first."
+ )
+ return None
+
+
+def _entry_field(entry, key: str, fallback_key: str, default):
+ """ls entries are dicts (camelCase) or objects (snake_case); read both."""
+ if isinstance(entry, dict):
+ return entry.get(key, default)
+ return getattr(entry, fallback_key, default)
+
+
+def _filter_code_uris(entries) -> tuple[list[str], bool]:
+ """Pick file entries whose extension is supported by the AST extractor, capped.
+
+ Returns (uris, capped) where capped is True when the 200-file limit was hit
+ and there may be more matching files beyond the cap.
+ """
+ extractor = get_extractor()
+ uris: list[str] = []
+ for e in entries:
+ is_dir = _entry_field(e, "isDir", "is_dir", False)
+ if is_dir:
+ continue
+ entry_uri = _entry_field(e, "uri", "uri", "")
+ if not entry_uri:
+ continue
+ if extractor.supports(entry_uri):
+ uris.append(entry_uri)
+ if len(uris) > _CODE_SEARCH_FILE_CAP:
+ return uris[:_CODE_SEARCH_FILE_CAP], True
+ return uris, False
+
+
+async def code_outline(uri: str) -> str:
+ """Show a file's symbol structure — classes, functions, methods, and their line ranges.
+ Returns a structural map without reading implementation bodies.
+
+ Use to survey a file before deciding what to read. More efficient than reading the whole
+ file when you only need to locate a method or understand a file's API surface.
+ Typical workflow: code_search → code_outline → code_expand.
+
+ uri must be a viking:// file URI (not a directory)."""
+ err = _require_viking_uri(uri)
+ if err:
+ return err
+ service = get_service()
+ ctx = _get_ctx()
+ try:
+ content = await service.fs.read(uri, ctx=ctx)
+ except Exception as exc:
+ return f"Error: failed to read {uri}: {exc}"
+ if not isinstance(content, str):
+ return f"Error: {uri} is not text"
+ return outline_file(content, uri)
+
+
+async def code_search(query: str, uri: str) -> str:
+ """Search symbol names (class / function / method) by substring across a viking://
+ directory. Returns structured results: symbol type, class context, file URI, line range.
+
+ Use when you don't know which file contains the symbol you're looking for. Returns
+ structural context (class ownership, location) that raw text search does not provide.
+
+ Skip if you already know the exact file; use code_outline or Read directly.
+
+ Scans up to 200 source files. Narrow uri to a subdirectory for deeper coverage.
+ uri is required to avoid accidentally walking the entire VikingFS."""
+ err = _require_viking_uri(uri)
+ if err:
+ return err
+ if not query:
+ return "Error: empty query"
+
+ service = get_service()
+ ctx = _get_ctx()
+ try:
+ entries = await service.fs.ls(uri, ctx=ctx, recursive=True, output="original")
+ except Exception as exc:
+ return f"Error: failed to list {uri}: {exc}"
+
+ code_uris, capped = _filter_code_uris(entries or [])
+ if not code_uris:
+ return f"No supported source files found under {uri}"
+
+ semaphore = asyncio.Semaphore(_CODE_SEARCH_CONCURRENCY)
+
+ async def _read(u: str) -> Optional[tuple[str, str]]:
+ async with semaphore:
+ try:
+ body = await service.fs.read(u, ctx=ctx)
+ except Exception as exc:
+ logger.warning("code_search: read failed for %s: %s", u, exc)
+ return None
+ if isinstance(body, str):
+ return body, u
+ return None
+
+ fetched = await asyncio.gather(*[_read(u) for u in code_uris])
+ files = [pair for pair in fetched if pair is not None]
+ result = search_symbols(query, files)
+ if capped:
+ result += "\n\n(scanning stopped at 200-file cap; narrow uri to search more)"
+ return result
+
+
+async def code_expand(uri: str, symbol: str) -> str:
+ """Return the full source of a single named symbol (function, class, or method).
+ Reads only that symbol's body, avoiding the overhead of reading an entire file.
+
+ Use when you need the implementation of one specific symbol. For reading multiple
+ symbols from the same file, Read is often more efficient.
+
+ `symbol` accepts 'bar' (top-level) or 'Foo.bar' (method).
+ uri must be a viking:// file URI."""
+ err = _require_viking_uri(uri)
+ if err:
+ return err
+ if not symbol:
+ return "Error: empty symbol"
+
+ service = get_service()
+ ctx = _get_ctx()
+ try:
+ content = await service.fs.read(uri, ctx=ctx)
+ except Exception as exc:
+ return f"Error: failed to read {uri}: {exc}"
+ if not isinstance(content, str):
+ return f"Error: {uri} is not text"
+ return expand_symbol(content, uri, symbol)
+
+
# -- health ----------------------------------------------------------------
@@ -807,7 +961,7 @@ async def mcp_lifespan():
"""Run the MCP session manager. Call this inside the FastAPI lifespan."""
async with mcp.session_manager.run():
logger.info(
- "MCP endpoint ready (10 tools: find, search, read, list, remember, add_resource, grep, glob, forget, health)"
+ "MCP endpoint ready (13 tools: find, search, read, list, remember, add_resource, grep, glob, code_outline, code_search, code_expand, forget, health)"
)
yield
diff --git a/tests/mcp_benchmark/server.py b/tests/mcp_benchmark/server.py
new file mode 100644
index 000000000..1eee86883
--- /dev/null
+++ b/tests/mcp_benchmark/server.py
@@ -0,0 +1,228 @@
+"""Minimal stdio MCP server that exposes the 3 new code-navigation tools
+backed by the *actual* code_tools / extractor modules from the OpenViking
+repo. Stubs the heavy openviking dependencies (pyagfs, etc.) and maps
+viking:// URIs to local disk so we can drive an end-to-end MCP test
+without building the full openviking stack.
+
+URI scheme:
+ viking://local/<ABSOLUTE-PATH> -> /<ABSOLUTE-PATH> on local disk
+
+This is *only* for the end-to-end MCP verification. Production runs through
+openviking.server.mcp_endpoint with the real VikingFS.
+"""
+from __future__ import annotations
+
+import asyncio
+import importlib.util
+import logging
+import os
+import sys
+import types
+from pathlib import Path
+from typing import Optional
+
+ROOT = Path(__file__).parent.parent.parent
+
+# Stub openviking_cli.utils.get_logger so extractor.py imports cleanly.
+ovc = types.ModuleType("openviking_cli")
+ovc_utils = types.ModuleType("openviking_cli.utils")
+ovc_utils.get_logger = lambda name: logging.getLogger(name)
+sys.modules["openviking_cli"] = ovc
+sys.modules["openviking_cli.utils"] = ovc_utils
+
+for pkg in (
+ "openviking",
+ "openviking.parse",
+ "openviking.parse.parsers",
+ "openviking.parse.parsers.code",
+ "openviking.parse.parsers.code.ast",
+ "openviking.parse.parsers.code.ast.languages",
+):
+ m = types.ModuleType(pkg)
+ m.__path__ = []
+ sys.modules[pkg] = m
+
+
+def _load(name: str, rel: str):
+ spec = importlib.util.spec_from_file_location(name, ROOT / rel)
+ mod = importlib.util.module_from_spec(spec)
+ sys.modules[name] = mod
+ spec.loader.exec_module(mod)
+ return mod
+
+
+_load("openviking.parse.parsers.code.ast.skeleton",
+ "openviking/parse/parsers/code/ast/skeleton.py")
+_load("openviking.parse.parsers.code.ast.languages.base",
+ "openviking/parse/parsers/code/ast/languages/base.py")
+_load("openviking.parse.parsers.code.ast.languages.python",
+ "openviking/parse/parsers/code/ast/languages/python.py")
+_load("openviking.parse.parsers.code.ast.extractor",
+ "openviking/parse/parsers/code/ast/extractor.py")
+_load("openviking.parse.parsers.code.ast.code_tools",
+ "openviking/parse/parsers/code/ast/code_tools.py")
+
+from openviking.parse.parsers.code.ast.code_tools import ( # noqa: E402
+ expand_symbol,
+ outline_file,
+ search_symbols,
+)
+from openviking.parse.parsers.code.ast.extractor import get_extractor # noqa: E402
+
+from mcp.server.fastmcp import FastMCP # noqa: E402
+
+logger = logging.getLogger("openviking_mcp_test")
+
+mcp = FastMCP("openviking-code-tools-test")
+
+_VIKING_PREFIX = "viking://local"
+_CODE_SEARCH_FILE_CAP = 200
+_CODE_SEARCH_CONCURRENCY = 10
+
+
+def _uri_to_path(uri: str) -> Optional[Path]:
+ """Map viking://local/<abs-path> -> Path('<abs-path>'). None on bad URI."""
+ if not isinstance(uri, str) or not uri.startswith(_VIKING_PREFIX):
+ return None
+ rest = uri[len(_VIKING_PREFIX):]
+ if not rest.startswith("/"):
+ return None
+ return Path(rest)
+
+
+def _require_viking_uri(uri: str) -> Optional[str]:
+ if not isinstance(uri, str) or not uri.startswith("viking://"):
+ return (
+ "Error: only viking:// URIs are supported; "
+ "use add_resource to ingest local code as a viking:// resource first."
+ )
+ return None
+
+
+async def _read_text(uri: str) -> tuple[Optional[str], Optional[str]]:
+ """Returns (content, error_msg). Content is None iff error_msg is set."""
+ path = _uri_to_path(uri)
+ if path is None:
+ return None, f"Error: {uri} is not a viking://local URI in this test server"
+ try:
+ return await asyncio.to_thread(path.read_text, encoding="utf-8"), None
+ except FileNotFoundError as exc:
+ return None, f"Error: failed to read {uri}: {exc}"
+ except UnicodeDecodeError:
+ return None, f"Error: {uri} is not text"
+ except Exception as exc:
+ return None, f"Error: failed to read {uri}: {exc}"
+
+
+async def _walk(uri: str) -> tuple[Optional[list[str]], Optional[str]]:
+ """Recursively list viking:// URIs under a directory. Returns (uris, error)."""
+ root = _uri_to_path(uri)
+ if root is None or not root.is_dir():
+ return None, f"Error: failed to list {uri}: not a directory"
+ found: list[str] = []
+ try:
+ def _scan() -> list[str]:
+ out: list[str] = []
+ for p in root.rglob("*"):
+ if p.is_file():
+ out.append(f"{_VIKING_PREFIX}{p}")
+ return out
+ found = await asyncio.to_thread(_scan)
+ return found, None
+ except Exception as exc:
+ return None, f"Error: failed to list {uri}: {exc}"
+
+
+async def code_outline(uri: str) -> str:
+ """Show a file's symbol structure — classes, functions, methods, and their line ranges.
+ Returns a structural map without reading implementation bodies.
+
+ Use to survey a file before deciding what to read. More efficient than reading the whole
+ file when you only need to locate a method or understand a file's API surface.
+ Typical workflow: code_search → code_outline → code_expand.
+
+ uri must be a viking://local file URI in this test server."""
+ err = _require_viking_uri(uri)
+ if err:
+ return err
+ content, err = await _read_text(uri)
+ if err:
+ return err
+ return outline_file(content, uri)
+
+
+async def code_search(query: str, uri: str) -> str:
+ """Search symbol names (class / function / method) by substring across a viking://local directory.
+ Returns structured results: symbol type, class context, file URI, and line range.
+
+ Use when you don't know which file contains the symbol you're looking for. Returns
+ structural context (class ownership, location) that raw text search does not provide.
+
+ Skip if you already know the exact file; use code_outline or Read directly.
+
+ Scans up to 200 source files. Narrow uri to a subdirectory for deeper coverage."""
+ err = _require_viking_uri(uri)
+ if err:
+ return err
+ if not query:
+ return "Error: empty query"
+
+ all_uris, err = await _walk(uri)
+ if err:
+ return err
+
+ extractor = get_extractor()
+ code_uris: list[str] = []
+ for u in all_uris or []:
+ if extractor.supports(u):
+ code_uris.append(u)
+ if len(code_uris) >= _CODE_SEARCH_FILE_CAP:
+ break
+
+ if not code_uris:
+ return f"No supported source files found under {uri}"
+
+ capped = len(code_uris) >= _CODE_SEARCH_FILE_CAP
+ sem = asyncio.Semaphore(_CODE_SEARCH_CONCURRENCY)
+
+ async def _fetch(u: str):
+ async with sem:
+ body, ferr = await _read_text(u)
+ if ferr:
+ logger.warning("code_search: %s", ferr)
+ return None
+ return body, u
+
+ fetched = await asyncio.gather(*[_fetch(u) for u in code_uris])
+ files = [pair for pair in fetched if pair is not None]
+ result = search_symbols(query, files)
+ if capped:
+ result += "\n\n(scanning stopped at 200-file cap; narrow uri to search more)"
+ return result
+
+
+async def code_expand(uri: str, symbol: str) -> str:
+ """Return the full source of a single named symbol (function, class, or method).
+ Reads only that symbol's body, avoiding the overhead of reading an entire file.
+
+ Use when you need the implementation of one specific symbol. For reading multiple
+ symbols from the same file, Read is often more efficient.
+
+ `symbol` accepts 'bar' (top-level) or 'Foo.bar' (method).
+ uri must be a viking://local file URI in this test server."""
+ err = _require_viking_uri(uri)
+ if err:
+ return err
+ if not symbol:
+ return "Error: empty symbol"
+ content, err = await _read_text(uri)
+ if err:
+ return err
+ return expand_symbol(content, uri, symbol)
+
+
+if __name__ == "__main__":
+ mcp.run()
diff --git a/tests/parse/run_code_tests.py b/tests/parse/run_code_tests.py
new file mode 100644
index 000000000..091ef69a8
--- /dev/null
+++ b/tests/parse/run_code_tests.py
@@ -0,0 +1,62 @@
+#!/usr/bin/env python3
+"""Run tests/parse/test_code_tools.py without the full openviking dependency stack.
+
+Uses the same stub-then-load pattern as tests/mcp_benchmark/server.py.
+"""
+import importlib.util
+import logging
+import sys
+import types
+from pathlib import Path
+
+ROOT = Path(__file__).parent.parent.parent
+
+# Stub openviking_cli so extractor.py imports cleanly.
+ovc = types.ModuleType("openviking_cli")
+ovc_utils = types.ModuleType("openviking_cli.utils")
+ovc_utils.get_logger = lambda name: logging.getLogger(name)
+sys.modules["openviking_cli"] = ovc
+sys.modules["openviking_cli.utils"] = ovc_utils
+
+# Stub the openviking package hierarchy so __init__.py files are skipped.
+for pkg in (
+ "openviking",
+ "openviking.parse",
+ "openviking.parse.parsers",
+ "openviking.parse.parsers.code",
+ "openviking.parse.parsers.code.ast",
+ "openviking.parse.parsers.code.ast.languages",
+):
+ m = types.ModuleType(pkg)
+ m.__path__ = [str(ROOT / pkg.replace(".", "/"))]
+ sys.modules[pkg] = m
+
+
+def _load(name: str, rel: str):
+ spec = importlib.util.spec_from_file_location(name, ROOT / rel)
+ mod = importlib.util.module_from_spec(spec)
+ sys.modules[name] = mod
+ spec.loader.exec_module(mod)
+ return mod
+
+
+_load("openviking.parse.parsers.code.ast.skeleton",
+ "openviking/parse/parsers/code/ast/skeleton.py")
+_load("openviking.parse.parsers.code.ast.languages.base",
+ "openviking/parse/parsers/code/ast/languages/base.py")
+for lang in ("python", "js_ts", "go", "rust", "java", "cpp", "csharp", "php", "lua"):
+ _load(f"openviking.parse.parsers.code.ast.languages.{lang}",
+ f"openviking/parse/parsers/code/ast/languages/{lang}.py")
+_load("openviking.parse.parsers.code.ast.extractor",
+ "openviking/parse/parsers/code/ast/extractor.py")
+_load("openviking.parse.parsers.code.ast.code_tools",
+ "openviking/parse/parsers/code/ast/code_tools.py")
+
+if __name__ == "__main__":
+ import pytest
+ sys.exit(pytest.main([
+ str(Path(__file__).parent / "test_code_tools.py"),
+ "--noconftest",
+ "-o", "addopts=",
+ "-v",
+ ] + sys.argv[1:]))
diff --git a/tests/parse/test_code_tools.py b/tests/parse/test_code_tools.py
new file mode 100644
index 000000000..55a2333b2
--- /dev/null
+++ b/tests/parse/test_code_tools.py
@@ -0,0 +1,381 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+"""Tests for the code-navigation pure functions backing the
+code_outline / code_search / code_expand MCP tools."""
+
+from openviking.parse.parsers.code.ast.code_tools import (
+ expand_symbol,
+ outline_file,
+ search_symbols,
+)
+from openviking.parse.parsers.code.ast.extractor import get_extractor
+
+
+PY_SAMPLE = '''"""Module top doc."""
+
+import os
+from typing import List
+
+
+class Greeter:
+ """Greets people."""
+
+ def __init__(self, name: str):
+ self.name = name
+
+ def greet(self, who: str) -> str:
+ """Return a greeting."""
+ return f"Hello {who} from {self.name}"
+
+
+def make_greeter(name: str) -> Greeter:
+ return Greeter(name)
+'''
+
+
+# ---------------------------------------------------------------------------
+# Line numbers populated by extractors
+# ---------------------------------------------------------------------------
+
+
+class TestLineNumbers:
+ def test_python_class_and_method_lines(self):
+ skel = get_extractor().extract("greeter.py", PY_SAMPLE)
+ assert skel is not None
+ assert len(skel.classes) == 1
+ cls = skel.classes[0]
+ assert cls.name == "Greeter"
+ # Class spans from `class Greeter:` to end of greet body
+ assert cls.line_start == 7
+ assert cls.line_end >= 15
+
+ method_names = [m.name for m in cls.methods]
+ assert "__init__" in method_names
+ assert "greet" in method_names
+
+ greet = next(m for m in cls.methods if m.name == "greet")
+ assert greet.line_start == 13
+ assert greet.line_end == 15
+
+ def test_python_top_level_function_lines(self):
+ skel = get_extractor().extract("greeter.py", PY_SAMPLE)
+ assert len(skel.functions) == 1
+ fn = skel.functions[0]
+ assert fn.name == "make_greeter"
+ assert fn.line_start == 18
+ assert fn.line_end == 19
+
+ def test_unsupported_language_returns_none(self):
+ assert get_extractor().extract("readme.md", "# hello") is None
+
+
+GO_SAMPLE = """\
+package main
+
+type Greeter struct {
+\tName string
+}
+
+func (g *Greeter) Greet(who string) string {
+\treturn "Hello " + who
+}
+
+func MakeGreeter(name string) *Greeter {
+\treturn &Greeter{Name: name}
+}
+"""
+
+TS_SAMPLE = """\
+class Greeter {
+ name: string;
+ constructor(name: string) {
+ this.name = name;
+ }
+ greet(who: string): string {
+ return `Hello ${who}`;
+ }
+}
+
+function makeGreeter(name: string): Greeter {
+ return new Greeter(name);
+}
+"""
+
+RS_SAMPLE = """\
+pub struct Greeter {
+ pub name: String,
+}
+
+impl Greeter {
+ pub fn greet(&self, who: &str) -> String {
+ format!("Hello {}", who)
+ }
+}
+
+pub fn make_greeter(name: String) -> Greeter {
+ Greeter { name }
+}
+"""
+
+JAVA_SAMPLE = """\
+public class Greeter {
+ private String name;
+
+ public Greeter(String name) {
+ this.name = name;
+ }
+
+ public String greet(String who) {
+ return "Hello " + who;
+ }
+}
+"""
+
+CPP_SAMPLE = """\
+#include <string>
+
+class Greeter {
+public:
+ std::string greet(const std::string& who) {
+ return "Hello " + who;
+ }
+};
+"""
+
+CS_SAMPLE = """\
+public class Greeter {
+ public string Name { get; set; }
+ public string Greet(string who) {
+ return "Hello " + who;
+ }
+}
+"""
+
+PHP_SAMPLE = """\
+<?php
+
+class Greeter {
+ public $name;
+ public function greet($who) {
+ return "Hello $who";
+ }
+}
+
+function makeGreeter($name) {
+ return new Greeter();
+}
+"""
+
+LUA_SAMPLE = """\
+function Greeter:greet(who)
+ return "Hello " .. who
+end
+
+function makeGreeter(name)
+ return name
+end
+"""
+
+_LANG_SAMPLES = [
+ ("greeter.go", GO_SAMPLE, "Go"),
+ ("greeter.ts", TS_SAMPLE, "TypeScript"),
+ ("greeter.rs", RS_SAMPLE, "Rust"),
+ ("Greeter.java", JAVA_SAMPLE, "Java"),
+ ("greeter.cpp", CPP_SAMPLE, "C++"),
+ ("Greeter.cs", CS_SAMPLE, "C#"),
+ ("greeter.php", PHP_SAMPLE, "PHP"),
+ ("greeter.lua", LUA_SAMPLE, "Lua"),
+]
+
+
+class TestLineNumbersAllLanguages:
+ """Regression: every language extractor must populate non-zero line numbers.
+
+ Prior to this commit all extractors left line_start/line_end at the default
+ of 0. These tests ensure the node.start_point / end_point wiring is correct
+ for each supported language by asserting that every class and function in the
+ sample snippet carries a positive, ordered span.
+ """
+
+ def _check_non_zero(self, file_name: str, src: str, lang_name: str):
+ import pytest
+
+ ext = get_extractor()
+ if not ext.supports(file_name):
+ pytest.skip(f"tree-sitter grammar for {lang_name} not installed")
+ skel = ext.extract(file_name, src)
+ assert skel is not None, f"{lang_name}: parse returned None"
+
+ symbols = []
+ for cls in skel.classes:
+ symbols.append((f"class {cls.name}", cls.line_start, cls.line_end))
+ for m in cls.methods:
+ symbols.append((f"{cls.name}.{m.name}", m.line_start, m.line_end))
+ for fn in skel.functions:
+ symbols.append((f"fn {fn.name}", fn.line_start, fn.line_end))
+
+ assert symbols, f"{lang_name}: no symbols extracted"
+ for sym, start, end in symbols:
+ assert start > 0, f"{lang_name} {sym}: line_start is 0 (not populated)"
+ assert end >= start, f"{lang_name} {sym}: line_end {end} < line_start {start}"
+
+ def test_go_line_numbers(self):
+ self._check_non_zero("greeter.go", GO_SAMPLE, "Go")
+
+ def test_typescript_line_numbers(self):
+ self._check_non_zero("greeter.ts", TS_SAMPLE, "TypeScript")
+
+ def test_rust_line_numbers(self):
+ self._check_non_zero("greeter.rs", RS_SAMPLE, "Rust")
+
+ def test_java_line_numbers(self):
+ self._check_non_zero("Greeter.java", JAVA_SAMPLE, "Java")
+
+ def test_cpp_line_numbers(self):
+ self._check_non_zero("greeter.cpp", CPP_SAMPLE, "C++")
+
+ def test_csharp_line_numbers(self):
+ self._check_non_zero("Greeter.cs", CS_SAMPLE, "C#")
+
+ def test_php_line_numbers(self):
+ self._check_non_zero("greeter.php", PHP_SAMPLE, "PHP")
+
+ def test_lua_line_numbers(self):
+ self._check_non_zero("greeter.lua", LUA_SAMPLE, "Lua")
+
+
+# ---------------------------------------------------------------------------
+# outline_file
+# ---------------------------------------------------------------------------
+
+
+class TestOutlineFile:
+ def test_outline_python(self):
+ out = outline_file(PY_SAMPLE, "greeter.py")
+ assert out.startswith("greeter.py [Python,")
+ assert "20 lines" in out # 19 newlines + 1
+ assert "imports: os, typing.List" in out
+ assert 'module: "Module top doc."' in out
+ assert "class Greeter L7-" in out
+ assert "+ __init__(self, name: str) L10-11" in out
+ assert "+ greet(self, who: str) -> str L13-15" in out
+ assert "def make_greeter(name: str) -> Greeter L18-19" in out
+ # outline must not leak docstrings (it's a navigation view)
+ assert '"""' not in out
+ assert "Return a greeting" not in out
+
+ def test_outline_empty_file(self):
+ # Empty content: no symbols, but the header should still appear
+ out = outline_file("", "empty.py")
+ assert out.startswith("empty.py [Python,")
+ # 0 newlines + 1 = 1 line in our convention; tolerated either way
+ assert "lines]" in out
+
+ def test_outline_unsupported_language(self):
+ out = outline_file("# nothing", "notes.md")
+ assert out == "Error: unsupported language for notes.md"
+
+
+# ---------------------------------------------------------------------------
+# search_symbols
+# ---------------------------------------------------------------------------
+
+
+SECOND_FILE = '''def greet():
+ pass
+
+
+class Other:
+ def helper(self):
+ pass
+'''
+
+
+class TestSearchSymbols:
+ def test_substring_case_insensitive(self):
+ result = search_symbols(
+ "greet",
+ [(PY_SAMPLE, "greeter.py"), (SECOND_FILE, "other.py")],
+ )
+ # Four substring hits on leaf name "greet":
+ # greeter.py : Greeter (class), Greeter.greet (method), make_greeter (fn)
+ # other.py : greet (top-level fn)
+ assert result.startswith('4 matches for "greet"')
+ assert "scanned 2 files" in result
+ assert "greeter.py" in result
+ assert "other.py" in result
+ assert "Greeter.greet" in result
+ assert "make_greeter" in result
+
+ def test_qualified_name_search(self):
+ # Searching the full qualified name must also match.
+ result = search_symbols("Greeter.greet", [(PY_SAMPLE, "greeter.py")])
+ assert "1 matches" in result
+ assert "Greeter.greet" in result
+
+ def test_query_only_matches_leaf_name(self):
+ result = search_symbols("helper", [(SECOND_FILE, "other.py")])
+ assert "1 matches" in result
+ assert "Other.helper" in result
+
+ def test_no_match(self):
+ result = search_symbols("nonexistent_xyz", [(PY_SAMPLE, "greeter.py")])
+ assert result.startswith("No matches")
+ assert "scanned 1 files" in result
+
+ def test_empty_query(self):
+ assert search_symbols("", [(PY_SAMPLE, "greeter.py")]) == "Error: empty query"
+
+ def test_skips_unsupported_silently(self):
+ # Markdown file is silently skipped (still counts toward scanned total)
+ result = search_symbols(
+ "greet",
+ [(PY_SAMPLE, "greeter.py"), ("# heading", "notes.md")],
+ )
+ assert "scanned 2 files" in result
+ assert "notes.md" not in result
+
+
+# ---------------------------------------------------------------------------
+# expand_symbol
+# ---------------------------------------------------------------------------
+
+
+class TestExpandSymbol:
+ def test_expand_top_level_function(self):
+ out = expand_symbol(PY_SAMPLE, "greeter.py", "make_greeter")
+ assert out.startswith("# greeter.py L18-19 (make_greeter)")
+ assert "def make_greeter(name: str) -> Greeter:" in out
+ assert "return Greeter(name)" in out
+
+ def test_expand_class(self):
+ out = expand_symbol(PY_SAMPLE, "greeter.py", "Greeter")
+ assert "(Greeter)" in out
+ assert "class Greeter:" in out
+ assert "def greet" in out # body included
+
+ def test_expand_qualified_method(self):
+ out = expand_symbol(PY_SAMPLE, "greeter.py", "Greeter.greet")
+ assert "(Greeter.greet)" in out
+ assert "def greet(self, who: str) -> str:" in out
+ # Should NOT include __init__ or class header
+ assert "class Greeter" not in out
+ assert "__init__" not in out
+
+ def test_expand_bare_method_resolves_to_first_match(self):
+ # bare 'greet' should find the method via class walk (first match)
+ out = expand_symbol(PY_SAMPLE, "greeter.py", "greet")
+ assert "(Greeter.greet)" in out
+ assert "def greet" in out
+
+ def test_expand_missing_symbol(self):
+ out = expand_symbol(PY_SAMPLE, "greeter.py", "does_not_exist")
+ assert out == "Error: symbol 'does_not_exist' not found in greeter.py"
+
+ def test_expand_unsupported_language(self):
+ out = expand_symbol("# hello", "readme.md", "anything")
+ assert out == "Error: unsupported language for readme.md"
+
+ def test_expand_qualified_missing_class(self):
+ out = expand_symbol(PY_SAMPLE, "greeter.py", "NoSuchClass.greet")
+ assert "symbol 'NoSuchClass.greet' not found" in out
diff --git a/tests/server/test_mcp_endpoint_code.py b/tests/server/test_mcp_endpoint_code.py
new file mode 100644
index 000000000..fa5df16f2
--- /dev/null
+++ b/tests/server/test_mcp_endpoint_code.py
@@ -0,0 +1,375 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+
+"""Tests for the code-navigation MCP tools (code_outline / code_search /
+code_expand) in openviking/server/mcp_endpoint.py.
+
+The pure formatters in openviking.parse.parsers.code.ast.code_tools are
+covered by tests/parse/test_code_tools.py. These tests cover the MCP wiring:
+URI validation, service.fs.read / service.fs.ls plumbing, extension filtering,
+the 200-file cap, and error mapping.
+"""
+
+from types import SimpleNamespace
+
+import pytest
+
+from openviking.server.dependencies import set_service
+from openviking.server.identity import RequestContext, Role
+from openviking.server.mcp_endpoint import (
+ _filter_code_uris,
+ _mcp_ctx,
+ _require_viking_uri,
+ code_expand,
+ code_outline,
+ code_search,
+)
+from openviking_cli.session.user_id import UserIdentifier
+
+DEFAULT_CTX = RequestContext(
+ user=UserIdentifier.the_default_user("test_user"),
+ role=Role.ROOT,
+)
+
+
+PY_SAMPLE = '''"""Module top doc."""
+
+
+class Greeter:
+ def greet(self, who: str) -> str:
+ return f"Hello {who}"
+
+
+def make_greeter() -> Greeter:
+ return Greeter()
+'''
+
+
[email protected](autouse=True)
+def _set_mcp_identity(service):
+ """Set identity contextvar and wire service for all tests."""
+ set_service(service)
+ token = _mcp_ctx.set(DEFAULT_CTX)
+ yield
+ _mcp_ctx.reset(token)
+
+
+def _patch_fs(monkeypatch, service, *, read=None, ls=None):
+ """Replace service.fs.read / .ls with async fakes."""
+ if read is not None:
+ monkeypatch.setattr(service.fs, "read", read)
+ if ls is not None:
+ monkeypatch.setattr(service.fs, "ls", ls)
+
+
+# ---------------------------------------------------------------------------
+# _require_viking_uri (internal helper, but small contract worth pinning)
+# ---------------------------------------------------------------------------
+
+
+class TestRequireVikingUri:
+ def test_accepts_viking_uri(self):
+ assert _require_viking_uri("viking://resources/foo.py") is None
+
+ def test_rejects_local_path(self):
+ msg = _require_viking_uri("/tmp/foo.py")
+ assert msg is not None
+ assert "viking://" in msg
+
+ def test_rejects_http_url(self):
+ msg = _require_viking_uri("https://example.com/foo.py")
+ assert msg is not None
+
+ def test_rejects_non_string(self):
+ assert _require_viking_uri(None) is not None # type: ignore[arg-type]
+
+
+# ---------------------------------------------------------------------------
+# _filter_code_uris
+# ---------------------------------------------------------------------------
+
+
+class TestFilterCodeUris:
+ def test_keeps_supported_extensions(self):
+ entries = [
+ {"uri": "viking://r/a.py", "isDir": False},
+ {"uri": "viking://r/b.md", "isDir": False},
+ {"uri": "viking://r/c.ts", "isDir": False},
+ {"uri": "viking://r/d.txt", "isDir": False},
+ ]
+ uris, capped = _filter_code_uris(entries)
+ assert uris == ["viking://r/a.py", "viking://r/c.ts"]
+ assert capped is False
+
+ def test_skips_directories(self):
+ entries = [
+ {"uri": "viking://r/sub", "isDir": True},
+ {"uri": "viking://r/a.py", "isDir": False},
+ ]
+ uris, capped = _filter_code_uris(entries)
+ assert uris == ["viking://r/a.py"]
+ assert capped is False
+
+ def test_supports_object_entries(self):
+ entries = [
+ SimpleNamespace(uri="viking://r/a.py", is_dir=False),
+ SimpleNamespace(uri="viking://r/sub", is_dir=True),
+ ]
+ uris, capped = _filter_code_uris(entries)
+ assert uris == ["viking://r/a.py"]
+ assert capped is False
+
+ def test_caps_at_200(self):
+ entries = [{"uri": f"viking://r/f{i}.py", "isDir": False} for i in range(250)]
+ uris, capped = _filter_code_uris(entries)
+ assert len(uris) == 200
+ assert capped is True
+
+ def test_exactly_200_not_capped(self):
+ entries = [{"uri": f"viking://r/f{i}.py", "isDir": False} for i in range(200)]
+ uris, capped = _filter_code_uris(entries)
+ assert len(uris) == 200
+ assert capped is False
+
+
+# ---------------------------------------------------------------------------
+# code_outline
+# ---------------------------------------------------------------------------
+
+
+class TestCodeOutline:
+ async def test_rejects_non_viking_uri(self, service):
+ out = await code_outline("/tmp/foo.py")
+ assert "viking://" in out
+
+ async def test_outline_via_fs_read(self, service, monkeypatch):
+ captured = {}
+
+ async def fake_read(uri, ctx=None, **_):
+ captured["uri"] = uri
+ captured["ctx"] = ctx
+ return PY_SAMPLE
+
+ _patch_fs(monkeypatch, service, read=fake_read)
+
+ out = await code_outline("viking://resources/greeter.py")
+ assert captured["uri"] == "viking://resources/greeter.py"
+ assert captured["ctx"] == DEFAULT_CTX
+ assert "class Greeter" in out
+ assert "def make_greeter" in out
+ assert " L" in out # line spans rendered
+
+ async def test_unsupported_language_returns_sentinel(self, service, monkeypatch):
+ async def fake_read(uri, ctx=None, **_):
+ return "# heading"
+
+ _patch_fs(monkeypatch, service, read=fake_read)
+ out = await code_outline("viking://resources/notes.md")
+ assert out.startswith("Error: unsupported language")
+
+ async def test_read_failure(self, service, monkeypatch):
+ async def fake_read(uri, ctx=None, **_):
+ raise RuntimeError("boom")
+
+ _patch_fs(monkeypatch, service, read=fake_read)
+ out = await code_outline("viking://resources/x.py")
+ assert out.startswith("Error: failed to read")
+ assert "boom" in out
+
+ async def test_non_text_content(self, service, monkeypatch):
+ async def fake_read(uri, ctx=None, **_):
+ return b"\x00\x01binary"
+
+ _patch_fs(monkeypatch, service, read=fake_read)
+ out = await code_outline("viking://resources/x.py")
+ assert out.endswith("is not text")
+
+
+# ---------------------------------------------------------------------------
+# code_search
+# ---------------------------------------------------------------------------
+
+
+class TestCodeSearch:
+ async def test_rejects_non_viking_uri(self, service):
+ out = await code_search("foo", "/tmp/dir")
+ assert "viking://" in out
+
+ async def test_empty_query(self, service):
+ out = await code_search("", "viking://resources")
+ assert out == "Error: empty query"
+
+ async def test_lists_and_searches(self, service, monkeypatch):
+ ls_calls = {}
+ read_uris: list[str] = []
+
+ async def fake_ls(uri, ctx=None, recursive=False, output=None, **_):
+ ls_calls["uri"] = uri
+ ls_calls["ctx"] = ctx
+ ls_calls["recursive"] = recursive
+ ls_calls["output"] = output
+ return [
+ {"uri": "viking://r/a.py", "isDir": False},
+ {"uri": "viking://r/sub", "isDir": True},
+ {"uri": "viking://r/b.md", "isDir": False},
+ {"uri": "viking://r/c.py", "isDir": False},
+ ]
+
+ async def fake_read(uri, ctx=None, **_):
+ read_uris.append(uri)
+ if uri.endswith("a.py"):
+ return PY_SAMPLE
+ if uri.endswith("c.py"):
+ return "def other():\n pass\n"
+ return ""
+
+ _patch_fs(monkeypatch, service, ls=fake_ls, read=fake_read)
+
+ out = await code_search("greet", "viking://r")
+ assert ls_calls["recursive"] is True
+ assert ls_calls["output"] == "original"
+ assert ls_calls["ctx"] == DEFAULT_CTX
+ # b.md must be filtered out before any read happens
+ assert "viking://r/b.md" not in read_uris
+ assert set(read_uris) == {"viking://r/a.py", "viking://r/c.py"}
+ # search hits Greeter + Greeter.greet in a.py
+ assert "viking://r/a.py" in out
+ assert "Greeter" in out
+
+ async def test_empty_directory(self, service, monkeypatch):
+ async def fake_ls(uri, ctx=None, recursive=False, output=None, **_):
+ return []
+
+ _patch_fs(monkeypatch, service, ls=fake_ls)
+ out = await code_search("greet", "viking://empty")
+ assert "No supported source files" in out
+
+ async def test_no_code_files(self, service, monkeypatch):
+ async def fake_ls(uri, ctx=None, recursive=False, output=None, **_):
+ return [{"uri": "viking://r/notes.md", "isDir": False}]
+
+ _patch_fs(monkeypatch, service, ls=fake_ls)
+ out = await code_search("greet", "viking://r")
+ assert "No supported source files" in out
+
+ async def test_ls_failure(self, service, monkeypatch):
+ async def fake_ls(uri, ctx=None, recursive=False, output=None, **_):
+ raise RuntimeError("ls denied")
+
+ _patch_fs(monkeypatch, service, ls=fake_ls)
+ out = await code_search("greet", "viking://r")
+ assert out.startswith("Error: failed to list")
+ assert "ls denied" in out
+
+ async def test_read_failures_are_skipped(self, service, monkeypatch):
+ async def fake_ls(uri, ctx=None, recursive=False, output=None, **_):
+ return [
+ {"uri": "viking://r/a.py", "isDir": False},
+ {"uri": "viking://r/b.py", "isDir": False},
+ ]
+
+ async def fake_read(uri, ctx=None, **_):
+ if uri.endswith("b.py"):
+ raise RuntimeError("denied")
+ return PY_SAMPLE
+
+ _patch_fs(monkeypatch, service, ls=fake_ls, read=fake_read)
+ out = await code_search("greet", "viking://r")
+ # Search should still report the matches from a.py despite b.py failing.
+ assert "viking://r/a.py" in out
+ assert "Greeter" in out
+
+ async def test_file_cap_warning(self, service, monkeypatch):
+ async def fake_ls(uri, ctx=None, recursive=False, output=None, **_):
+ return [{"uri": f"viking://r/f{i}.py", "isDir": False} for i in range(250)]
+
+ async def fake_read(uri, ctx=None, **_):
+ return PY_SAMPLE
+
+ _patch_fs(monkeypatch, service, ls=fake_ls, read=fake_read)
+ out = await code_search("greet", "viking://r")
+ assert "200-file cap" in out
+
+ async def test_no_cap_warning_below_threshold(self, service, monkeypatch):
+ async def fake_ls(uri, ctx=None, recursive=False, output=None, **_):
+ return [{"uri": "viking://r/a.py", "isDir": False}]
+
+ async def fake_read(uri, ctx=None, **_):
+ return PY_SAMPLE
+
+ _patch_fs(monkeypatch, service, ls=fake_ls, read=fake_read)
+ out = await code_search("greet", "viking://r")
+ assert "200-file cap" not in out
+
+
+# ---------------------------------------------------------------------------
+# code_expand
+# ---------------------------------------------------------------------------
+
+
+class TestCodeExpand:
+ async def test_rejects_non_viking_uri(self, service):
+ out = await code_expand("/tmp/foo.py", "Greeter")
+ assert "viking://" in out
+
+ async def test_empty_symbol(self, service):
+ out = await code_expand("viking://r/a.py", "")
+ assert out == "Error: empty symbol"
+
+ async def test_expand_bare_symbol(self, service, monkeypatch):
+ captured = {}
+
+ async def fake_read(uri, ctx=None, **_):
+ captured["uri"] = uri
+ captured["ctx"] = ctx
+ return PY_SAMPLE
+
+ _patch_fs(monkeypatch, service, read=fake_read)
+ out = await code_expand("viking://r/a.py", "make_greeter")
+ assert captured["uri"] == "viking://r/a.py"
+ assert captured["ctx"] == DEFAULT_CTX
+ assert "(make_greeter)" in out
+ assert "def make_greeter" in out
+
+ async def test_expand_qualified_symbol(self, service, monkeypatch):
+ async def fake_read(uri, ctx=None, **_):
+ return PY_SAMPLE
+
+ _patch_fs(monkeypatch, service, read=fake_read)
+ out = await code_expand("viking://r/a.py", "Greeter.greet")
+ assert "(Greeter.greet)" in out
+ assert "def greet" in out
+
+ async def test_missing_symbol(self, service, monkeypatch):
+ async def fake_read(uri, ctx=None, **_):
+ return PY_SAMPLE
+
+ _patch_fs(monkeypatch, service, read=fake_read)
+ out = await code_expand("viking://r/a.py", "does_not_exist")
+ assert "not found" in out
+ assert "does_not_exist" in out
+
+ async def test_read_failure(self, service, monkeypatch):
+ async def fake_read(uri, ctx=None, **_):
+ raise RuntimeError("boom")
+
+ _patch_fs(monkeypatch, service, read=fake_read)
+ out = await code_expand("viking://r/a.py", "Greeter")
+ assert out.startswith("Error: failed to read")
+ assert "boom" in out
+
+ async def test_non_text_content(self, service, monkeypatch):
+ async def fake_read(uri, ctx=None, **_):
+ return b"\x00binary"
+
+ _patch_fs(monkeypatch, service, read=fake_read)
+ out = await code_expand("viking://r/a.py", "Greeter")
+ assert out.endswith("is not text")
+
+ async def test_unsupported_language(self, service, monkeypatch):
+ async def fake_read(uri, ctx=None, **_):
+ return "# heading"
+
+ _patch_fs(monkeypatch, service, read=fake_read)
+ out = await code_expand("viking://r/notes.md", "anything")
+ assert out.startswith("Error: unsupported language")