otter-kr
Deterministic, read-only source-repository evidence server that answers what exists in a Python repository via a single compatibility research router tool.
Run admitted Python evidence operations: tracked-file inventory and parse health, names, imports, tests, structural complexity, repeated literals/groups, structural duplicates, type discriminations, exact/structural/historical/behavioral neighborhoods, graph topology, carrier guards, and external field affinity.
Run composite operations: seed evidence projection, term-change evidence, representation inventories, and review packets.
Run Git evidence operations: bounded history, snapshots, hotspots, normalized co-change (global/file/pair), branch additions, temporal and commit-message distributions, topic commits and hunks, first-parent topic walks/families, rename identity, and line origins.
Supply
repository_rootandoperation(required), plus optionalpath,term,limit,lines,left_path,right_path, andsince_unix_time.Receive structured reports with counts, source locations, stable ordering, query bounds, warnings, and provenance, or structured rejections for invalid/unsupported requests.
Rely on evidence only: it does not import or execute target code, infer semantics, score quality, or recommend refactorings.
Provides evidence operations for Git repositories, including bounded history, snapshots, hotspots, co-change analysis, branch additions, commit-message distributions, topic commits, rename identity, and line origins.
Provides evidence operations for Python source code, including tracked-file inventory, parse health, names, imports, tests, complexity, repeated literals, structural duplicates, type discriminations, neighborhoods, and graph topology.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@otter-kr Find all occurrences of 'payment_processor' in /home/user/project"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
otter-kr
Deterministic source-repository evidence for coding agents, exposed through FastMCP. The evidence layer answers what exists in a repository; the calling agent remains responsible for interpretation and engineering judgment.
Current capability
Operation-specific stateless tools expose deterministic Python and Git evidence operations. The
legacy research tool remains as a compatibility router for clients that cannot yet select typed
tools directly. Current Python evidence covers tracked-file inventory and parse health, names, imports, tests, complexity,
repeated literals and groups, structural duplicates, type discriminations, exact/structural/
historical/behavioral neighborhoods, graph topology, seed-scoped carrier guards, and external
field affinity. Composite operations project seed evidence, term-change evidence, representation
inventories, and review
packets without adding design judgments.
Git evidence covers bounded history, snapshots, hotspots, normalized co-change at global/file/pair scope, branch additions, temporal and commit-message distributions, topic commits and hunks, first-parent topic walks and families, rename identity, and line origins. Reports retain explicit query bounds, stable ordering, source locations, warnings, and provenance. Unsupported or invalid requests return structured rejections rather than widening the analysis silently.
The product remains Python-only and evidence-only: it does not import or execute target code,
infer semantic concepts, assign quality scores, or recommend refactorings. The detailed admission
boundaries and remaining research work live in BACKLOG.md.
Python structural complexity
Call python_structural_complexity with a repository_root and a measure. The report
gives a count and source location for each tracked Python function and method.
Each nested function is measured in its own row. Docstrings, decorators, defaults, and
signature annotations are outside the measured body.
operandscounts distinct declared parameters, body names, maximal attribute chains, and typed literal values. An expression-rooted chain such asitems[0].namecontributes the chain and its receiver inputs,itemsand0. A lambda receives a function diagnostic.operationscounts occurrences of assignments, arithmetic, Boolean and comparison operators, calls, attribute and subscript lookups, and collection displays. Augmented assignment contributes two operations. Each attribute hop contributes one. A collection display and a constructor call each contribute one operation in addition to any operations in their children. Control flow such asifandreturncontributes through its expressions and bodies. Ordinarytrystatements likewise contribute through their clauses. Araisecontributes through its exception and cause expressions. A comprehension contributes one operation at the enclosing scope. A synchronousforcontributes through its target, iterable, body, andelseclause once as written. Other unadmitted syntax produces a function diagnostic.pathsstarts at one for straight-line code, ending a route at a return, an explicit raise, or fall-through. Anifhas two alternatives even with a compound condition. A loop contributes a zero-iteration and a populated alternative. A comprehension contributes one continuation at the enclosing scope. Two successive simple loops give three structural paths, and two nested loops give four. Each reachable sequential region adds its alternatives beyond the first, and each loop doubles the count for its body. An iterable expression contributes its alternatives before that loop's choice. Atrywith ordinaryexceptclauses counts its body and each handler as structural alternatives. A following statement is reachable if any of those clauses can fall through. The measure does not resolve exception types or infer which expressions can raise. A conditional expression outside a comprehension adds two alternatives, with any choices in its condition counted before those alternatives. Loopelse,trywithelseorfinally, andexcept*produce a function diagnostic.
Python function and class profiles
Pass an absolute repository_root, a repository-relative path to a tracked Python file,
and a dotted qualified_name. Use names such as Class.method or outer.inner for
nested definitions. These examples use the otter-kr checkout as the target repository.
[
{
"tool": "python_function_profile",
"arguments": {
"repository_root": "/absolute/path/to/otter-kr",
"path": "src/otter_kr/review_packet.py",
"qualified_name": "collect_review_packet"
}
},
{
"tool": "python_function_profiles",
"arguments": {
"repository_root": "/absolute/path/to/otter-kr",
"targets": [
{"path": "src/otter_kr/server.py", "qualified_name": "_run_operation"},
{"path": "src/otter_kr/python_graph.py", "qualified_name": "build_python_import_graph"}
]
}
},
{
"tool": "python_class_profile",
"arguments": {
"repository_root": "/absolute/path/to/otter-kr",
"path": "src/otter_kr/evidence_graph.py",
"qualified_name": "EvidenceGraph",
"limit": 4
}
}
]A function profile includes its source span, cyclomatic complexity, primitive density from parameter annotations, and structural measures for operands, operations, and paths. It also reports locations for explicit
ifpredicates, comparisons, and attribute reads and writes in the function body. Each site list shows up to 16 entries, with a total count and a truncation flag. Comprehension sites include source spans, counts of generators and filters, and flags for conditional results and nested comprehensions. These observations describe the comprehension's internal structure alongside the enclosing operation and path counts.A batch accepts 1–16 targets, parses each selected file once, and returns one profile per target in request order. Check each profile's
match_statusfor missing, ambiguous, or unavailable definitions.A class profile includes its source span and primitive density for annotations in the class body. It profiles direct methods in source order, with a default limit of 8 and a maximum of 16. Each method includes up to 16 observed read or write sites for directly annotated fields accessed through the receiver's name. Check
methods_truncatedand each method's field-access truncation flag.
A structural measure returns a diagnostic when its syntax rules cannot produce a count.
Other measurements in the same profile can still be available. For a change review, use
git_review_packet_files with the changed paths, a history start timestamp
(since_unix_time), and a limit to get file-level context. Then use
python_function_profiles to inspect the changed definitions and follow their source
locations. Check the packet's history and dependency truncation flags when using that
context to support a finding.
Related MCP server: CodeGraph MCP
Evidence layer for refactoring skills
otter-kr is intended to provide citeable, deterministic evidence for otter-skills and other refactoring skills. It reports facts such as locations, counts, relationships, and history; an LLM or human uses those facts to make and validate design decisions. The MCP deliberately does not replace the reasoning, representation, testing, or refactoring skills that consume its evidence.
The refactoring situation catalog maps the current evidence operations to hypotheses and otter-skills hand-offs without turning heuristics into automatic smell labels.
Develop with uv
Install the pinned environment and run all checks:
uv sync
uv run pytest
uv run ruff check .
uv run ruff format --check .Generate the provider contract directly from the live MCP schemas when a client cannot use runtime tool discovery:
uv run otter-kr-contract > /tmp/otter-kr-contract.jsonThis is generated output, not a second interface definition. Do not hand-edit a provider guide's
tool names or fields; consume this contract or connect the provider directly to the MCP server.
Provider projects may keep curated workflow examples as JSON tests and validate them with
uv run otter-kr-contract --validate-examples provider-examples.json; unknown tools, fields, and
missing required arguments then fail in CI.
Run the stdio server:
uv run otter-krAn MCP client can launch it from any directory with an entry like this (replace the path):
{
"mcpServers": {
"otter-kr": {
"command": "uv",
"args": [
"--directory",
"/absolute/path/to/otter-kr",
"run",
"otter-kr"
]
}
}
}Prefer the operation-specific tools, such as python_inventory, python_names, and git_history.
Each typed tool names its required inputs directly: python_names requires term, while bounded
Git tools require since_unix_time and limit. The compatibility research router accepts the
same admitted operations and fields for older clients.
Design boundary
Repository analysis lives in framework-independent modules under src/otter_kr. The MCP server
only validates transport inputs and presents structured results. Language is explicit in each
report, leaving room for analyzers for other languages without changing the evidence contract.
Available Tools
1 toolresearchResearch a repositoryCRead-onlyIdempotent
Dispatch admitted research operations and reject the remainder.
Inputs: operation (required), repository_root (required), path, term, +5 more. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 1 tool
With only one tool, there is no possibility of overlap or misselection. The single tool is unambiguous as the only entry point.
The lone tool name 'research' is a bare word and does not establish a predictable verb_noun convention. There is no inconsistency, but there is also no coherent pattern to evaluate.
One tool is on the thin side, but the narrow admission/dispatch purpose could plausibly be served by a single operation. The surface feels minimal rather than well-scoped.
The server only dispatches admitted research operations and rejects the remainder. There are no tools for submitting, admitting, listing, or tracking research operations, so the surface is severely incomplete for a research workflow.
Maintenance
Related MCP Connectors
Code intelligence for coding agents: semantic, AST, graph, and full-text search. 279+ languages.
Ask a codebase what calls what: search, blast radius, paths between symbols, and diffs.
Ask who calls a route, what a change breaks or who reads a field, across a system's repos.
Deterministic context layer for your codebase: change impact, blast radius, answers with receipts.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to semantically navigate codebases via an AST index, supporting symbol search, usage lookup, module exploration, and dependency analysis.MIT
- FlicenseNot gradedqualityBmaintenanceEnables AI coding agents to interrogate a local repository deterministically for symbols, dependencies, call paths, routes, tests, and Git impact, returning verified structured evidence with exact line citations instead of requiring the whole codebase to be read.261 PyPI4-
- AlicenseNot gradedqualityBmaintenanceEnables AI agents and terminal users to query codebases for callers, impact, tests, dependencies, and refactor previews using static AST analysis, with every match accounted for and uncertain relationships clearly marked.1,067 npm2MIT
- AlicenseNot gradedqualityCmaintenanceEnables token-bounded, read-only hybrid code search across local repositories by fusing literal matches with AST symbol relations to return high-signal snippets, line ranges, and call metadata.1MIT