Server data from the Official MCP Registry
Rank supplied codebase search hits by relevance and recency, with file-owner context.
About
Rank supplied codebase search hits by relevance and recency, with file-owner context.
Security Report
codescout is a pure local computation tool that ranks caller-supplied search hits by a fixed formula, with no network, shell, or filesystem access beyond reading the CLI input file. Input validation is strict and path-naming, dependencies are the official MCP SDK and zod, and no secrets or malicious patterns were found. No meaningful security concerns were identified. Supply chain analysis found 3 known vulnerabilities in dependencies (0 critical, 2 high severity). Package verification found 1 issue.
8 files analyzed · 5 issues found
Security scores are indicators to help you make informed decisions, not guarantees. Always review permissions before connecting any MCP server.
Permissions Required
This plugin requests these system permissions. Most are normal for its category.
How to Install
Add this to your MCP configuration file:
{
"mcpServers": {
"codescout": {
"command": "npx",
"args": [
"-y",
"@reneturcios/codescout@0.1.0"
]
}
}
}Some servers take additional arguments. See the repository for details.
Documentation
View on GitHubFrom the project's GitHub README.
codescout
A codebase search is only half the job: once a search returns dozens of files, someone still has to decide which ones to open first. codescout makes that decision with one fixed, inspectable rule. You hand it the hits you already have — for each one, the file it is in, how many matches the file holds, how many days have passed since the file last changed, and, when you know it, who owns the file — and it hands back the hits ranked, best first, each with its score and the owner context attached. It runs no search of its own and touches no index; the ranking rule is the whole tool.
Every hit is scored the same way: matches * 100 - last_modified_days. A hundred points per match means
relevance dominates, while each day of age quietly
drags a file down — an old file with a single match can
score below zero, and that negative score is reported
as-is rather than clamped. Ranking follows the score,
and ties are settled in a fixed order: more matches
first, then the more recently changed file, then the
path in code-unit order. Because the rule never
changes, the same set of hits always produces the same
ranked list, whatever order you supplied them in.
Only the top of the list comes back: limit caps how
many results are returned and defaults to 10. Each
returned entry carries a rank, its 1-based position
in the returned list, alongside the echoed path,
matches, last_modified_days, and owner. Ownership
has one pinned judgement call: an owner that is absent,
empty, or only whitespace means the file is unowned,
and its owner is reported as null; any other owner
string is echoed exactly as supplied. The counts report
how many hits went in and how many came back.
Malformed input — a missing or empty hit list, a hit
that is not an object, a missing, empty, or non-string
path, a matches count that is missing, fractional,
or below 1, a last_modified_days that is missing,
fractional, or negative, a non-string owner, or a
limit below 1 — is a validation error naming the
offending path, with no partial result. Two hits for
the same path are an error naming the duplicated path.
Unknown extra fields are ignored.
CLI
npx @reneturcios/codescout rank --input args.json
npx @reneturcios/codescout --version
args.json contains the full arguments object:
{
"hits": [
{
"path": "src/search/rank.ts",
"matches": 14,
"last_modified_days": 2,
"owner": "alice"
},
{
"path": "src/legacy/old-index.ts",
"matches": 1,
"last_modified_days": 240
},
{
"path": "src/search/tokenize.ts",
"matches": 9,
"last_modified_days": 30,
"owner": "bob"
}
],
"limit": 2
}
The ranked list is printed as JSON:
{
"results": [
{
"path": "src/search/rank.ts",
"matches": 14,
"last_modified_days": 2,
"owner": "alice",
"score": 1398,
"rank": 1
},
{
"path": "src/search/tokenize.ts",
"matches": 9,
"last_modified_days": 30,
"owner": "bob",
"score": 870,
"rank": 2
}
],
"counts": {
"hits": 3,
"returned": 2
}
}
The third hit scores 1 * 100 - 240 = -140, so the
limit of 2 leaves it out entirely.
Exit codes: 0 on success, 1 on a runtime error
(including an unreadable or invalid input file, or
invalid input), 2 on a usage error.
MCP server
npx -y @reneturcios/codescout mcp
MCP client config:
{
"mcpServers": {
"codescout": {
"command": "npx",
"args": ["-y", "@reneturcios/codescout", "mcp"]
}
}
}
Tools
-
rank_search_results— Rank caller-supplied codebase search hits by a pinned relevance and recency score, with file-owner context attached.hits(array, required, at least 1 item) — the search hits to rank, in the caller's order; each item:path(string, required, non-empty) — file the hit is inmatches(integer, required, at least 1) — number of matches in the filelast_modified_days(integer, required, at least 0) — days since the file last changedowner(string, optional) — file owner; absent, empty, or whitespace-only means unowned
limit(integer, optional, at least 1, default 10) — maximum results to return
Returns
{results, counts}, whereresultsholds one{path, matches, last_modified_days, owner, score, rank}per returned hit in ranking order (ownerisnullwhen unowned,scoreismatches * 100 - last_modified_days, andrankis 1-based by position in the returned list), andcountsis{hits, returned}.
Docker
docker run -i ghcr.io/cloudcorprecords/codescout
docker run --rm -v "$PWD:/w" ghcr.io/cloudcorprecords/codescout rank --input /w/args.json
Development
npm install
npm run build # tsc -> dist/
npm test # tsx --test test/*.test.ts (pure local, no network)
npm run dev # run the CLI from source
License
MIT — Copyright (c) 2026 Rene Turcios
Reviews
No reviews yet
Be the first to review this server!
More Developer Tools MCP Servers
Rea
Freeby Morluto · Developer Tools
Reverse engineer anything from your terminal or agent with one CLI and MCP server.
Paperclip
Freeby Paperclipai · Developer Tools
Trending hip-hop artist momentum scores across four cultural dimensions.
Scrapling
Freeby D4Vinci · Developer Tools
Web scraping with stealth HTTP, real browsers, and Cloudflare bypass. CSS selectors supported.
Git
Freeby Modelcontextprotocol · Developer Tools
Read, search, and manipulate Git repositories programmatically
Toleno
Freeby Toleno · Developer Tools
Toleno Network MCP Server — Manage your Toleno mining account with Claude AI using natural language.
MCP Marketplace
Freeby mcp-marketplace · Developer Tools
Search and install MCP servers from inside your AI client.
