Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 8 additions & 1 deletion REQUIREMENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

> **Note:** This document is automatically generated and verified against the live test suite by `scripts/generate_requirements.py` and `tests/backend/test_requirements_sync.py`.

**Test Verification Baseline:** **1352 Automated Tests** (988 Pytest Backend + 314 Vitest Frontend + 50 Playwright E2E).
**Test Verification Baseline:** **1357 Automated Tests** (993 Pytest Backend + 314 Vitest Frontend + 50 Playwright E2E).

---

Expand Down Expand Up @@ -1022,6 +1022,13 @@ code results are enriched with signature/kind/ast_symbol_id from SQLite._
- `test_wait_for_db_retries_and_success`
- `test_wait_for_db_exhausts_retries`

#### `tests/test_db_write_channel_and_custom_routes.py` (5 tests)
- `test_database_write_channel_serializes_concurrent_sqlite_writers` - _Verifies DatabaseWriteChannel queues concurrent producers through a single writer thread without SQLite lock errors or interleaving._
- `test_general_csharp_custom_route_and_verb_attributes` - _Verifies custom C# route and HTTP verb attributes are resolved generically from class declarations and inheritance chains._
- `test_typescript_class_field_arrow_methods_and_axios_api_prefix_matching` - _Verifies TS class field arrow functions are extracted as Class.method symbols and their relative axios calls match /api/v{n} routes._
- `test_permalinks_are_opt_in_and_direct_tool_aliases_work` - _Verifies find_routes and search omit permalinks by default (until include_permalinks=True) and direct tool calls accept common parameter aliases._
- `test_code_mode_disabled_omits_execute_script_and_sse_post_routes_to_mcp` - _Verifies CODE_MODE_ENABLED=false omits execute_script from get_tool_definitions() and McpPingMiddleware routes POST /sse to /mcp._

#### `tests/test_delete_local_path.py` (4 tests)
- `test_delete_local_path_cleans_all_relational_tables_and_vectors` - _Verify DELETE /admin/api/paths/{id} removes rows from all 6 file-scoped tables and the vector store._
- `test_delete_local_path_with_shared_repo_only_purges_deleted_path_prefix` - _Verify deleting one local path that shares a repo name ('local') removes only its own files and vectors._
Expand Down
7 changes: 5 additions & 2 deletions app/mcp/handlers/diagnostic_handlers.py
Original file line number Diff line number Diff line change
Expand Up @@ -16,17 +16,20 @@ def _get_tools_attr(name, default):


async def handle_diagnose_issue(
issue_text: Annotated[str, Field(description="Raw stack trace, exception log, HTTP failure payload, or bug symptom report across Python, TypeScript/JS/TSX, C#, COBOL, Go, Rust, Java, and C/C++.")],
issue_text: Annotated[Optional[str], Field(description="Raw stack trace, exception log, HTTP failure payload, or bug symptom report across Python, TypeScript/JS/TSX, C#, COBOL, Go, Rust, Java, and C/C++.")] = None,
repo: Annotated[Optional[str], Field(description="Optional repository name to scope stack frame, route, and semantic candidate resolution.")] = None,
context_lines: Annotated[int, Field(description="Surrounding source lines returned per resolved stack frame, clamped to 1..15 (default 5).")] = 5,
limit: Annotated[int, Field(description="Maximum semantic code candidates returned alongside resolved stack frames, clamped to 1..20 (default 5).")] = 5,
detail: Annotated[bool, Field(description="Set True to add full method bodies to call_chain steps and code, permalinks, callers, and callees to semantic_candidates (default False keeps the answer compact).")] = False,
query: Annotated[Optional[str], Field(description="Alias for `issue_text`. `issue_text` wins when both are given.")] = None,
error: Annotated[Optional[str], Field(description="Alias for `issue_text`. `issue_text` wins when both are given.")] = None,
) -> str:
"""Forensic triage: a ranked call chain with evidence lines, plus stack frames, routes, symbols, and semantic candidates."""
try:
enforce_tool_permission(Role.VIEWER)

text = (issue_text or "").strip()
raw_text = issue_text if (issue_text is not None and issue_text.strip()) else (query or error or "")
text = raw_text.strip()
if not text:
return json.dumps({
"call_chain": {"entry": None, "terms": [], "steps": [], "other_hits": [], "nodes_read": 0},
Expand Down
15 changes: 9 additions & 6 deletions app/mcp/handlers/file_handlers.py
Original file line number Diff line number Diff line change
Expand Up @@ -144,26 +144,29 @@ def _query_outline_rows(target_clean: str):


async def handle_read_file(
path: Annotated[str, Field(description="Relative or absolute file path within an indexed repository, watched directory, or local storage (supports Python, TypeScript/JS/TSX, C#, COBOL, Go, Rust, Java, C/C++, Markdown, and config files).")],
path: Annotated[Optional[str], Field(description="Relative or absolute file path within an indexed repository, watched directory, or local storage (supports Python, TypeScript/JS/TSX, C#, COBOL, Go, Rust, Java, C/C++, Markdown, and config files).")] = None,
repo: Annotated[Optional[str], Field(description="Optional repository name or 'local_storage' namespace. Recommended for relative paths or reconstructing ephemeral Git files from vector chunks.")] = None,
start_line: Annotated[Optional[int], Field(description="1-based inclusive starting line number (default 1). Pass next_start_line from a prior call to paginate long files.")] = None,
end_line: Annotated[Optional[int], Field(description="1-based inclusive ending line number (default end of file, bounded by read_file_max_lines=2000 per call).")] = None,
outline_only: Annotated[bool, Field(description="Set True to return the file's AST symbol outline (classes, methods, functions, signatures, line ranges) instead of full source text.")] = False,
limit: Annotated[int, Field(description="Maximum AST symbols returned per page when outline_only=True, clamped to 1..500 (default 150).")] = 150,
offset: Annotated[int, Field(description="0-based AST symbol offset when outline_only=True (default 0). Advance via next_offset when has_more is True.")] = 0,
filepath: Annotated[Optional[str], Field(description="Alias for `path`. `path` wins when both are given.")] = None,
file: Annotated[Optional[str], Field(description="Alias for `path`. `path` wins when both are given.")] = None,
) -> str:
"""Read bounded 1-based line slices or inspect the AST symbol outline (outline_only=True) for an indexed file."""
eff_path = path if (path is not None and path.strip()) else (filepath or file or "")
try:
enforce_tool_permission(Role.VIEWER)

if outline_only:
return json.dumps(_read_file_outline_payload(path=path, repo=repo, limit=limit, offset=offset))
return json.dumps(_read_file_outline_payload(path=eff_path, repo=repo, limit=limit, offset=offset))

reader_fn = _get_tools_attr("get_file_reader_service", get_file_reader_service)
reader = reader_fn()

result = reader.read_file(
path=path,
path=eff_path,
repo=repo,
start_line=start_line,
end_line=end_line,
Expand All @@ -182,7 +185,7 @@ async def handle_read_file(
next_start_line = (e_line + 1) if (has_more and e_line is not None) else None

payload: Dict[str, Any] = {
"file": _strip_repo_prefix(result.get("filepath") or path),
"file": _strip_repo_prefix(result.get("filepath") or eff_path),
"lines": [s_line, e_line],
"total_lines": t_lines,
}
Expand All @@ -196,14 +199,14 @@ async def handle_read_file(
return json.dumps(payload, separators=(",", ":"))

except ForbiddenError as fe:
logger.warning(f"Forbidden error in handle_read_file ({path}): {fe}")
logger.warning(f"Forbidden error in handle_read_file ({eff_path}): {fe}")
return json.dumps({"error": f"Forbidden: {str(fe)}", "forbidden": True})
except FileNotFoundError as fne:
return json.dumps({"error": f"File not found: {str(fne)}"})
except ValueError as ve:
return json.dumps({"error": str(ve)})
except Exception as e:
logger.error(f"Error reading file '{path}': {e}")
logger.error(f"Error reading file '{eff_path}': {e}")
return json.dumps({"error": f"Error reading file: {str(e)}"})


Expand Down
21 changes: 15 additions & 6 deletions app/mcp/handlers/grep_handlers.py
Original file line number Diff line number Diff line change
Expand Up @@ -69,7 +69,7 @@ def _sanitize_match_lines(match: Dict[str, Any]) -> Dict[str, Any]:


async def handle_grep_code(
pattern: Annotated[str, Field(description="Exact literal string or regular expression to match across source files (Python, TypeScript/JS/TSX, C#, COBOL, Go, Rust, Java, C/C++, Markdown, configs).")],
pattern: Annotated[Optional[str], Field(description="Exact literal string or regular expression to match across source files (Python, TypeScript/JS/TSX, C#, COBOL, Go, Rust, Java, C/C++, Markdown, configs).")] = None,
repo: Annotated[Optional[str], Field(description="Optional repository name or 'local_storage' to scope search. Omit to scan all indexed sources.")] = None,
path_glob: Annotated[Optional[str], Field(description="Optional path filter. With wildcards it is an fnmatch glob ('*.cs', 'app/services/*'); without wildcards it is a file or folder ('Services_V2', 'src/app/main.py').")] = None,
is_regex: Annotated[bool, Field(description="Set True to evaluate pattern as a Python regular expression; False (default) matches literal text. If a literal search finds nothing and the pattern looks like a regex (for example 'A|B'), the search runs again as a regex and pattern_mode says so.")] = False,
Expand All @@ -78,23 +78,28 @@ async def handle_grep_code(
limit: Annotated[int, Field(description="Maximum matched lines per page, clamped to 1..100 (default 30).")] = 30,
offset: Annotated[int, Field(description="0-based match offset for pagination (default 0). Advance by next_offset when has_more is True.")] = 0,
path: Annotated[Optional[str], Field(description="Alias for path_glob (a file, folder, or glob). path_glob wins when both are given.")] = None,
include_permalinks: Annotated[bool, Field(description="Include file-level Git web permalinks on matched file groups (default False keeps output compact).")] = False,
query: Annotated[Optional[str], Field(description="Alias for `pattern`. `pattern` wins when both are given.")] = None,
filepath: Annotated[Optional[str], Field(description="Alias for `path_glob` (a file, folder, or glob). `path_glob` wins when both are given.")] = None,
file: Annotated[Optional[str], Field(description="Alias for `path_glob` (a file, folder, or glob). `path_glob` wins when both are given.")] = None,
) -> str:
"""Deterministic literal and regex pattern search across indexed repositories with bounded line lengths and pagination."""
try:
enforce_tool_permission(Role.VIEWER)
eff_pattern = pattern if (pattern is not None and pattern != "") else (query if query is not None else "")
reader_fn = _resolve_reader_factory()
reader = reader_fn()

safe_limit = max(1, min(int(limit if limit is not None else 30), 100))
safe_offset = max(0, int(offset if offset is not None else 0))
safe_context = max(0, min(int(context_lines if context_lines is not None else 2), 10))
needed = safe_offset + safe_limit + 1
path_filter = path_glob or path
path_filter = path_glob or path or filepath or file

def _search(as_regex: bool) -> List[Dict[str, Any]]:
if needed <= 100:
raw_result = reader.grep_code(
pattern=pattern,
pattern=eff_pattern,
repo=repo,
path_glob=path_filter,
is_regex=as_regex,
Expand All @@ -104,7 +109,7 @@ def _search(as_regex: bool) -> List[Dict[str, Any]]:
)
return raw_result.get("matches", [])
raw_result = execute_code_grep(
pattern=pattern,
pattern=eff_pattern,
storage_root=reader.storage_root,
indexed_paths=reader._get_authorized_indexed_paths(),
persistent_repos=reader._get_authorized_persistent_repos(),
Expand All @@ -122,7 +127,7 @@ def _search(as_regex: bool) -> List[Dict[str, Any]]:

pattern_mode = "regex" if is_regex else "literal"
all_matches = _search(is_regex)
if not all_matches and not is_regex and looks_like_regex(pattern):
if not all_matches and not is_regex and looks_like_regex(eff_pattern):
all_matches = _search(True)
pattern_mode = "regex (the literal text had no matches, so the pattern ran as a regex)"

Expand All @@ -131,7 +136,11 @@ def _search(as_regex: bool) -> List[Dict[str, Any]]:
sanitized_matches = [_sanitize_match_lines(m) for m in page_slice]
next_offset = (safe_offset + safe_limit) if has_more else None

shared_repo, files = group_grep_matches(sanitized_matches, block_separators=safe_context > 0)
shared_repo, files = group_grep_matches(
sanitized_matches,
block_separators=safe_context > 0,
include_permalinks=bool(include_permalinks),
)
payload: Dict[str, Any] = {"total_matches": len(all_matches)}
if pattern_mode != ("regex" if is_regex else "literal"):
payload["pattern_mode"] = pattern_mode
Expand Down
55 changes: 38 additions & 17 deletions app/mcp/handlers/route_handlers.py
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,14 @@ def belongs(call_url: str, call_method: str) -> bool:
return belongs


def _query_route_handlers(conn, local_roots: LocalSourceRoots, clean_q: Optional[str], method_clean: Optional[str], repo_clean: Optional[str]) -> List[Dict[str, Any]]:
def _query_route_handlers(
conn,
local_roots: LocalSourceRoots,
clean_q: Optional[str],
method_clean: Optional[str],
repo_clean: Optional[str],
include_permalinks: bool = False,
) -> List[Dict[str, Any]]:
sql = (
"SELECT r.id, r.repo, r.filepath, r.framework, r.http_method, r.path_pattern, "
"r.handler_symbol, r.start_line, r.end_line, g.url as git_url, g.commit_sha, g.provider "
Expand Down Expand Up @@ -75,23 +82,31 @@ def _query_route_handlers(conn, local_roots: LocalSourceRoots, clean_q: Optional
if dedup_key in seen_routes:
continue
seen_routes.add(dedup_key)
permalink = format_git_permalink(
r["git_url"], r["commit_sha"], rel_path, r["start_line"], r["end_line"], provider=r["provider"]
)
all_routes.append({
item: Dict[str, Any] = {
"repo": r["repo"],
"method": r["http_method"],
"path": r["path_pattern"],
"framework": r["framework"],
"handler": r["handler_symbol"],
"file": rel_path,
"lines": [r["start_line"], r["end_line"]],
"permalink": permalink,
})
}
if include_permalinks:
item["permalink"] = format_git_permalink(
r["git_url"], r["commit_sha"], rel_path, r["start_line"], r["end_line"], provider=r["provider"]
)
all_routes.append(item)
return all_routes


def _query_route_callers(conn, local_roots: LocalSourceRoots, clean_q: Optional[str], method_clean: Optional[str], repo_clean: Optional[str]) -> List[Dict[str, Any]]:
def _query_route_callers(
conn,
local_roots: LocalSourceRoots,
clean_q: Optional[str],
method_clean: Optional[str],
repo_clean: Optional[str],
include_permalinks: bool = False,
) -> List[Dict[str, Any]]:
sql = (
"SELECT c.id, c.repo, c.filepath, c.http_method, c.url_pattern, c.caller_symbol, "
"c.line_number, g.url as git_url, g.commit_sha, g.provider "
Expand Down Expand Up @@ -135,18 +150,19 @@ def _query_route_callers(conn, local_roots: LocalSourceRoots, clean_q: Optional[
continue
seen_callers.add(dedup_key)

permalink = format_git_permalink(
c["git_url"], c["commit_sha"], rel_path, c["line_number"], c["line_number"], provider=c["provider"]
)
all_callers.append({
item: Dict[str, Any] = {
"repo": c["repo"],
"method": c["http_method"],
"url": url_pat,
"caller": caller_sym,
"file": rel_path,
"line": c["line_number"],
"permalink": permalink,
})
}
if include_permalinks:
item["permalink"] = format_git_permalink(
c["git_url"], c["commit_sha"], rel_path, c["line_number"], c["line_number"], provider=c["provider"]
)
all_callers.append(item)
return all_callers


Expand All @@ -157,6 +173,10 @@ async def handle_find_routes(
repo: Annotated[Optional[str], Field(description="Optional repository name filter.")] = None,
limit: Annotated[int, Field(description="Maximum results per section per page, clamped to 1..200 (default 50).")] = 50,
offset: Annotated[int, Field(description="0-based offset for pagination (default 0). Advance via next_offset when has_more is True.")] = 0,
include_permalinks: Annotated[bool, Field(description="Include Git web permalinks on returned routes and callers (default False keeps answers compact).")] = False,
path: Annotated[Optional[str], Field(description="Alias for `query` (route path or URL pattern filter). `query` wins when both are given.")] = None,
path_query: Annotated[Optional[str], Field(description="Alias for `query` (route path or URL pattern filter). `query` wins when both are given.")] = None,
route: Annotated[Optional[str], Field(description="Alias for `query` (route path or URL pattern filter). `query` wins when both are given.")] = None,
) -> str:
"""Discover HTTP/API route endpoints and/or client HTTP callers across indexed repositories with bounded pagination."""
try:
Expand All @@ -167,7 +187,8 @@ async def handle_find_routes(
if clean_kind not in ("handlers", "callers", "both"):
return json.dumps({"error": f"Unsupported kind '{kind}'. Valid kinds are 'handlers', 'callers', or 'both'."})

clean_q = query.strip() if query and query.strip() else None
raw_q = query if (query and query.strip()) else (path or path_query or route or "")
clean_q = raw_q.strip() if raw_q and raw_q.strip() else None
method_clean = method.strip().upper() if method and method.strip() else None
repo_clean = repo.strip() if repo and repo.strip() else None
safe_limit = max(1, min(int(limit if limit is not None else 50), 200))
Expand All @@ -176,12 +197,12 @@ async def handle_find_routes(
with _get_tools_attr("get_db_connection", get_db_connection)() as conn:
local_roots = LocalSourceRoots.load(conn)
all_routes = (
_query_route_handlers(conn, local_roots, clean_q, method_clean, repo_clean)
_query_route_handlers(conn, local_roots, clean_q, method_clean, repo_clean, include_permalinks=bool(include_permalinks))
if clean_kind in ("handlers", "both")
else []
)
all_callers = (
_query_route_callers(conn, local_roots, clean_q, method_clean, repo_clean)
_query_route_callers(conn, local_roots, clean_q, method_clean, repo_clean, include_permalinks=bool(include_permalinks))
if clean_kind in ("callers", "both")
else []
)
Expand Down
Loading
Loading