narrow-mcp 0.1.0__tar.gz

narrow_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Manik Prakash
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

narrow_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,126 @@
+Metadata-Version: 2.4
+Name: narrow-mcp
+Version: 0.1.0
+Summary: MCP server that narrows large low-density files (logs, CSV, JSON, HTML) to the verbatim spans relevant to an intent, verified against source.
+Author: Manik Prakash
+License-Expression: MIT
+Project-URL: Repository, https://github.com/manik-prakash/narrow-mcp
+Project-URL: Issues, https://github.com/manik-prakash/narrow-mcp/issues
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Build Tools
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp[cli]>=2.0.0
+Requires-Dist: anthropic>=0.40.0
+Requires-Dist: openai>=1.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.24.0; extra == "dev"
+Requires-Dist: pyyaml>=6.0; extra == "dev"
+Dynamic: license-file
+
+# narrow-mcp
+
+<!-- mcp-name: io.github.manik-prakash/narrow-mcp -->
+
+An MCP server that narrows large, low-density non-source files (logs, test
+output, CSV, JSON, HTML) down to the verbatim spans relevant to a stated
+intent -- verified against the original file, never a summary.
+
+## Why
+
+Coding agents burn context reading large low-density files. A 40k-token log
+might hold a few hundred tokens of signal. This tool:
+
+1. Runs deterministic narrowing first (grep-style search, structural
+   parsing per file type, sampling) -- free, fast, zero LLM cost.
+2. If that alone resolves the query with confidence (e.g. an exact CSV
+   "null column" query), returns it directly. No LLM call at all.
+3. Otherwise passes only the narrowed candidates (never the raw file) to a
+   cheap, fast selector model that returns line ranges and a one-line
+   reason -- never prose.
+4. Re-reads the chosen line ranges from the **original file on disk** and
+   returns that verbatim text. The selector's own words are never trusted
+   or returned -- only its line-number coordinates, which get verified.
+5. If the selector fails, times out, or returns something invalid, falls
+   back to the deterministic candidate set rather than failing outright.
+
+Non-goals: source code retrieval (use LSP/tree-sitter/ast-grep), prose
+summarization, local/self-hosted models.
+
+## Status
+
+v1, single file per call. Four file types: log/build-output, CSV, JSON
+(single document or JSONL), HTML.
+
+## Development
+
+```
+pip install -e ".[dev]"
+pytest
+python eval/run_eval.py          # mocked selector, free
+python eval/run_eval.py --live   # real selector call, needs an API key (see Configuration)
+```
+
+## Configuration
+
+**You only need to set one API key.** The provider is auto-detected from
+whichever key is present -- no separate provider/model config required:
+
+| If you set...       | Provider used | Default model                                  |
+|----------------------|----------------|-------------------------------------------------|
+| `ANTHROPIC_API_KEY`   | `anthropic`    | `claude-haiku-4-5`                              |
+| `OPENAI_API_KEY`      | `openai`       | `gpt-5-nano`                                    |
+| `OPENROUTER_API_KEY`  | `openrouter`   | `openrouter/free` (see below)                   |
+| *(none)*              | `anthropic`    | `claude-haiku-4-5` (calls just always fall back to the deterministic path) |
+
+If more than one key is set, priority is Anthropic > OpenAI > OpenRouter.
+Override anything explicitly with the env vars below.
+
+### Using OpenRouter's free models
+
+OpenRouter still requires its own API key even for $0-cost models -- set
+`OPENROUTER_API_KEY` and you're done, no other config needed. It defaults to
+**`openrouter/free`**, a meta-router that auto-picks among whichever
+tool-calling-capable models are currently free, so it never goes stale the
+way hardcoding one specific `:free` model name would.
+
+To see the current free-model roster live (it rotates) and pick a specific
+one instead of the meta-router:
+
+```
+narrow-mcp-list-free-models
+```
+
+Then set `NARROW_MCP_SELECTOR_MODEL=<id>` to whichever one you want.
+
+OpenRouter's free tier is rate-limited (20 req/min; 50 req/day, or 1000/day
+once the account has $10+ lifetime spend) -- fine for interactive use, worth
+knowing about for batch runs.
+
+### All environment variables
+
+- `NARROW_MCP_SELECTOR_PROVIDER` -- `anthropic` | `openai` | `openrouter`.
+  Overrides auto-detection.
+- `NARROW_MCP_SELECTOR_MODEL` -- overrides the provider's default model.
+- `NARROW_MCP_SELECTOR_API_KEY_ENV` -- overrides which env var holds the key.
+- `NARROW_MCP_SELECTOR_TIMEOUT_S` (default `3.0`)
+- `NARROW_MCP_MAX_CANDIDATE_CHARS`, `NARROW_MCP_MAX_CANDIDATES`,
+  `NARROW_MCP_CONTEXT_LINES`, `NARROW_MCP_RIPGREP_PATH`,
+  `NARROW_MCP_MAX_JSON_BYTES`
+
+## Registering with Claude Code
+
+```
+claude mcp add narrow-mcp -- uvx narrow-mcp
+```
+
+Verify current `claude mcp add` flag syntax against `claude mcp add --help`
+before relying on the above -- CLI flags change across releases.

narrow_mcp-0.1.0/README.md

@@ -0,0 +1,98 @@
+# narrow-mcp
+
+<!-- mcp-name: io.github.manik-prakash/narrow-mcp -->
+
+An MCP server that narrows large, low-density non-source files (logs, test
+output, CSV, JSON, HTML) down to the verbatim spans relevant to a stated
+intent -- verified against the original file, never a summary.
+
+## Why
+
+Coding agents burn context reading large low-density files. A 40k-token log
+might hold a few hundred tokens of signal. This tool:
+
+1. Runs deterministic narrowing first (grep-style search, structural
+   parsing per file type, sampling) -- free, fast, zero LLM cost.
+2. If that alone resolves the query with confidence (e.g. an exact CSV
+   "null column" query), returns it directly. No LLM call at all.
+3. Otherwise passes only the narrowed candidates (never the raw file) to a
+   cheap, fast selector model that returns line ranges and a one-line
+   reason -- never prose.
+4. Re-reads the chosen line ranges from the **original file on disk** and
+   returns that verbatim text. The selector's own words are never trusted
+   or returned -- only its line-number coordinates, which get verified.
+5. If the selector fails, times out, or returns something invalid, falls
+   back to the deterministic candidate set rather than failing outright.
+
+Non-goals: source code retrieval (use LSP/tree-sitter/ast-grep), prose
+summarization, local/self-hosted models.
+
+## Status
+
+v1, single file per call. Four file types: log/build-output, CSV, JSON
+(single document or JSONL), HTML.
+
+## Development
+
+```
+pip install -e ".[dev]"
+pytest
+python eval/run_eval.py          # mocked selector, free
+python eval/run_eval.py --live   # real selector call, needs an API key (see Configuration)
+```
+
+## Configuration
+
+**You only need to set one API key.** The provider is auto-detected from
+whichever key is present -- no separate provider/model config required:
+
+| If you set...       | Provider used | Default model                                  |
+|----------------------|----------------|-------------------------------------------------|
+| `ANTHROPIC_API_KEY`   | `anthropic`    | `claude-haiku-4-5`                              |
+| `OPENAI_API_KEY`      | `openai`       | `gpt-5-nano`                                    |
+| `OPENROUTER_API_KEY`  | `openrouter`   | `openrouter/free` (see below)                   |
+| *(none)*              | `anthropic`    | `claude-haiku-4-5` (calls just always fall back to the deterministic path) |
+
+If more than one key is set, priority is Anthropic > OpenAI > OpenRouter.
+Override anything explicitly with the env vars below.
+
+### Using OpenRouter's free models
+
+OpenRouter still requires its own API key even for $0-cost models -- set
+`OPENROUTER_API_KEY` and you're done, no other config needed. It defaults to
+**`openrouter/free`**, a meta-router that auto-picks among whichever
+tool-calling-capable models are currently free, so it never goes stale the
+way hardcoding one specific `:free` model name would.
+
+To see the current free-model roster live (it rotates) and pick a specific
+one instead of the meta-router:
+
+```
+narrow-mcp-list-free-models
+```
+
+Then set `NARROW_MCP_SELECTOR_MODEL=<id>` to whichever one you want.
+
+OpenRouter's free tier is rate-limited (20 req/min; 50 req/day, or 1000/day
+once the account has $10+ lifetime spend) -- fine for interactive use, worth
+knowing about for batch runs.
+
+### All environment variables
+
+- `NARROW_MCP_SELECTOR_PROVIDER` -- `anthropic` | `openai` | `openrouter`.
+  Overrides auto-detection.
+- `NARROW_MCP_SELECTOR_MODEL` -- overrides the provider's default model.
+- `NARROW_MCP_SELECTOR_API_KEY_ENV` -- overrides which env var holds the key.
+- `NARROW_MCP_SELECTOR_TIMEOUT_S` (default `3.0`)
+- `NARROW_MCP_MAX_CANDIDATE_CHARS`, `NARROW_MCP_MAX_CANDIDATES`,
+  `NARROW_MCP_CONTEXT_LINES`, `NARROW_MCP_RIPGREP_PATH`,
+  `NARROW_MCP_MAX_JSON_BYTES`
+
+## Registering with Claude Code
+
+```
+claude mcp add narrow-mcp -- uvx narrow-mcp
+```
+
+Verify current `claude mcp add` flag syntax against `claude mcp add --help`
+before relying on the above -- CLI flags change across releases.

narrow_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,50 @@
+[project]
+name = "narrow-mcp"
+version = "0.1.0"
+description = "MCP server that narrows large low-density files (logs, CSV, JSON, HTML) to the verbatim spans relevant to an intent, verified against source."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Manik Prakash" }]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Operating System :: OS Independent",
+    "Topic :: Software Development :: Build Tools",
+]
+dependencies = [
+    "mcp[cli]>=2.0.0",
+    "anthropic>=0.40.0",
+    "openai>=1.0.0",
+]
+
+[project.urls]
+Repository = "https://github.com/manik-prakash/narrow-mcp"
+Issues = "https://github.com/manik-prakash/narrow-mcp/issues"
+
+[project.scripts]
+narrow-mcp = "narrow_mcp.mcp_handler:main"
+narrow-mcp-list-free-models = "narrow_mcp.list_free_models:main"
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0.0", "pytest-asyncio>=0.24.0", "pyyaml>=6.0"]
+
+[build-system]
+requires = ["setuptools>=77.0.0"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+narrow_mcp = ["narrowing/keyword_hints.toml"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]
+asyncio_mode = "auto"

narrow_mcp-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

narrow_mcp-0.1.0/src/narrow_mcp/__init__.py

@@ -0,0 +1 @@
+"""narrow_mcp: narrows large low-density files to the spans relevant to an intent."""

narrow_mcp-0.1.0/src/narrow_mcp/budget.py

@@ -0,0 +1,39 @@
+"""Candidate-budget enforcement. Standalone so policy can be tuned without touching narrowing logic."""
+
+from __future__ import annotations
+
+from .config import Budget
+from .models import Candidate
+
+
+def enforce(candidates: list[Candidate], budget: Budget) -> tuple[list[Candidate], int]:
+    """Truncate/prioritize candidates to fit the budget.
+
+    Returns (kept_candidates, truncated_count). Always keeps at least one
+    candidate if any were given. Prioritizes by score (highest first), then
+    by document order for ties.
+    """
+    if not candidates:
+        return [], 0
+
+    ordered = sorted(
+        enumerate(candidates), key=lambda pair: (-pair[1].score, pair[0])
+    )
+
+    kept: list[Candidate] = []
+    total_chars = 0
+    for _, candidate in ordered:
+        preview_len = len(candidate.preview_text)
+        if kept and (
+            len(kept) >= budget.max_candidates
+            or total_chars + preview_len > budget.max_candidate_chars
+        ):
+            continue
+        kept.append(candidate)
+        total_chars += preview_len
+
+    # Restore original document order for readability in the prompt.
+    kept_ids = {id(c) for c in kept}
+    kept_in_order = [c for c in candidates if id(c) in kept_ids]
+    truncated_count = len(candidates) - len(kept_in_order)
+    return kept_in_order, truncated_count

narrow_mcp-0.1.0/src/narrow_mcp/config.py

@@ -0,0 +1,78 @@
+"""All tunables live here. Loaded from environment variables with sane defaults."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+
+@dataclass
+class Budget:
+    max_candidate_chars: int = 8000
+    max_candidates: int = 30
+    max_context_lines_per_hit: int = 3
+
+
+@dataclass
+class SelectorConfig:
+    provider: str = "anthropic"
+    model: str = "claude-haiku-4-5"
+    api_key_env_var: str = "ANTHROPIC_API_KEY"
+    timeout_s: float = 3.0
+    max_retries: int = 0
+
+
+_PROVIDER_DEFAULTS: dict[str, dict[str, str]] = {
+    "anthropic": {"model": "claude-haiku-4-5", "api_key_env_var": "ANTHROPIC_API_KEY"},
+    "openai": {"model": "gpt-5-nano", "api_key_env_var": "OPENAI_API_KEY"},
+    # openrouter/free is a stable meta-router that auto-picks among currently
+    # free, tool-calling-capable models -- never goes stale the way a specific
+    # ":free" model id would as OpenRouter's free roster rotates.
+    "openrouter": {"model": "openrouter/free", "api_key_env_var": "OPENROUTER_API_KEY"},
+}
+
+
+def _autodetect_provider() -> str:
+    """Only used when NARROW_MCP_SELECTOR_PROVIDER is not explicitly set.
+    Priority: a directly-paid-for native provider before OpenRouter (the
+    $0-cost fallback, not the preferred option if the user already has a
+    native key). No key at all -> today's unchanged default.
+    """
+    if os.environ.get("ANTHROPIC_API_KEY"):
+        return "anthropic"
+    if os.environ.get("OPENAI_API_KEY"):
+        return "openai"
+    if os.environ.get("OPENROUTER_API_KEY"):
+        return "openrouter"
+    return "anthropic"
+
+
+@dataclass
+class Config:
+    budget: Budget
+    selector: SelectorConfig
+    ripgrep_path: str | None = None
+    max_json_bytes: int = 20_000_000
+
+    @classmethod
+    def load(cls) -> "Config":
+        budget = Budget(
+            max_candidate_chars=int(os.environ.get("NARROW_MCP_MAX_CANDIDATE_CHARS", 8000)),
+            max_candidates=int(os.environ.get("NARROW_MCP_MAX_CANDIDATES", 30)),
+            max_context_lines_per_hit=int(os.environ.get("NARROW_MCP_CONTEXT_LINES", 3)),
+        )
+        provider = os.environ.get("NARROW_MCP_SELECTOR_PROVIDER") or _autodetect_provider()
+        defaults = _PROVIDER_DEFAULTS.get(provider, _PROVIDER_DEFAULTS["anthropic"])
+        selector = SelectorConfig(
+            provider=provider,
+            model=os.environ.get("NARROW_MCP_SELECTOR_MODEL", defaults["model"]),
+            api_key_env_var=os.environ.get("NARROW_MCP_SELECTOR_API_KEY_ENV", defaults["api_key_env_var"]),
+            timeout_s=float(os.environ.get("NARROW_MCP_SELECTOR_TIMEOUT_S", 3.0)),
+            max_retries=int(os.environ.get("NARROW_MCP_SELECTOR_MAX_RETRIES", 0)),
+        )
+        return cls(
+            budget=budget,
+            selector=selector,
+            ripgrep_path=os.environ.get("NARROW_MCP_RIPGREP_PATH"),
+            max_json_bytes=int(os.environ.get("NARROW_MCP_MAX_JSON_BYTES", 20_000_000)),
+        )

narrow_mcp-0.1.0/src/narrow_mcp/file_type_detector.py

@@ -0,0 +1,113 @@
+"""Decide which narrowing strategy applies to a file, and refuse source/binary files.
+
+This is the single place the "no source-code retrieval" non-goal is enforced.
+"""
+
+from __future__ import annotations
+
+import csv
+import io
+import json
+from pathlib import Path
+
+from .models import FileTypeDecision
+
+SOURCE_EXTENSIONS = {
+    ".py", ".pyi", ".js", ".jsx", ".ts", ".tsx", ".mjs", ".cjs",
+    ".go", ".rs", ".java", ".kt", ".kts", ".c", ".h", ".cpp", ".hpp", ".cc",
+    ".cs", ".rb", ".php", ".swift", ".scala", ".m", ".mm", ".sh", ".ps1",
+    ".sql", ".lua", ".r", ".pl", ".ex", ".exs", ".clj", ".hs", ".dart",
+    ".vue", ".svelte",
+}
+
+CSV_EXTENSIONS = {".csv", ".tsv"}
+JSON_EXTENSIONS = {".json", ".jsonl", ".ndjson"}
+HTML_EXTENSIONS = {".html", ".htm", ".xhtml"}
+LOG_EXTENSIONS = {".log", ".txt", ".out", ".err"}
+
+SNIFF_BYTES = 8192
+
+
+def _is_binary(sample: bytes) -> bool:
+    return b"\x00" in sample
+
+
+def _sniff_json(sample: bytes) -> bool:
+    text = sample.decode("utf-8", errors="ignore").strip()
+    if not text:
+        return False
+    first = text[0]
+    if first not in "{[":
+        # Could still be JSONL where first line starts with { or [.
+        first_line = text.splitlines()[0].strip() if text.splitlines() else ""
+        if not first_line or first_line[0] not in "{[":
+            return False
+    try:
+        # Try parsing just the first line as a JSON value (JSONL check) or
+        # the whole sample as a prefix of a larger JSON document.
+        first_line = text.splitlines()[0]
+        json.loads(first_line)
+        return True
+    except (json.JSONDecodeError, ValueError):
+        # Might be a large single JSON document where the first line alone
+        # doesn't parse (e.g. pretty-printed). Fall back to bracket check.
+        return first in "{["
+
+
+def _sniff_csv(sample: bytes) -> bool:
+    text = sample.decode("utf-8", errors="ignore")
+    if not text.strip():
+        return False
+    try:
+        csv.Sniffer().sniff(text, delimiters=",;\t|")
+        return True
+    except csv.Error:
+        return False
+
+
+def _sniff_html(sample: bytes) -> bool:
+    text = sample.decode("utf-8", errors="ignore").lstrip()
+    lowered = text.lower()
+    return lowered.startswith("<!doctype html") or lowered.startswith("<html") or "<body" in lowered[:2000]
+
+
+def detect(path: Path) -> FileTypeDecision:
+    if not path.exists() or not path.is_file():
+        return FileTypeDecision(kind="unknown", confidence=0.0, reason="path does not exist or is not a file")
+
+    ext = path.suffix.lower()
+
+    if ext in SOURCE_EXTENSIONS:
+        return FileTypeDecision(
+            kind="source_refused",
+            confidence=1.0,
+            reason="source file — use LSP/tree-sitter/ast-grep tooling instead",
+        )
+
+    try:
+        with open(path, "rb") as f:
+            sample = f.read(SNIFF_BYTES)
+    except OSError as exc:
+        return FileTypeDecision(kind="unknown", confidence=0.0, reason=f"could not read file: {exc}")
+
+    if _is_binary(sample):
+        return FileTypeDecision(kind="binary_refused", confidence=1.0, reason="binary file not supported")
+
+    if ext in JSON_EXTENSIONS:
+        return FileTypeDecision(kind="json", confidence=1.0, reason=f"extension {ext}")
+    if ext in CSV_EXTENSIONS:
+        return FileTypeDecision(kind="csv", confidence=1.0, reason=f"extension {ext}")
+    if ext in HTML_EXTENSIONS:
+        return FileTypeDecision(kind="html", confidence=1.0, reason=f"extension {ext}")
+    if ext in LOG_EXTENSIONS:
+        return FileTypeDecision(kind="log", confidence=0.9, reason=f"extension {ext}")
+
+    # No recognized extension — sniff content.
+    if _sniff_json(sample):
+        return FileTypeDecision(kind="json", confidence=0.7, reason="content sniff: JSON-like")
+    if _sniff_html(sample):
+        return FileTypeDecision(kind="html", confidence=0.7, reason="content sniff: HTML-like")
+    if _sniff_csv(sample):
+        return FileTypeDecision(kind="csv", confidence=0.6, reason="content sniff: CSV-like")
+
+    return FileTypeDecision(kind="log", confidence=0.4, reason="no structured format detected, treating as text/log")

narrow_mcp-0.1.0/src/narrow_mcp/list_free_models.py

@@ -0,0 +1,74 @@
+"""Standalone setup-time helper -- NOT an MCP tool, not wired into the
+server. Prints OpenRouter's currently-free, tool-calling-capable models,
+fetched live (the free roster rotates, so this is never hardcoded).
+
+Usage:
+    narrow-mcp-list-free-models
+    python -m narrow_mcp.list_free_models
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+import urllib.error
+import urllib.request
+
+MODELS_URL = "https://openrouter.ai/api/v1/models?supported_parameters=tools"
+RECOMMENDED_MODEL = "openrouter/free"
+
+
+def _is_free(model: dict) -> bool:
+    model_id = model.get("id", "")
+    pricing = model.get("pricing", {})
+    return model_id.endswith(":free") or (
+        pricing.get("prompt") == "0" and pricing.get("completion") == "0"
+    )
+
+
+def fetch_free_models() -> list[dict]:
+    headers = {}
+    api_key = os.environ.get("OPENROUTER_API_KEY")
+    if api_key:
+        headers["Authorization"] = f"Bearer {api_key}"
+
+    req = urllib.request.Request(MODELS_URL, headers=headers)
+    with urllib.request.urlopen(req, timeout=10) as resp:
+        payload = json.loads(resp.read().decode("utf-8"))
+
+    models = payload.get("data", [])
+    return [m for m in models if _is_free(m)]
+
+
+def main() -> None:
+    print(f"RECOMMENDED (zero-maintenance default, auto-selects among current free models):\n  {RECOMMENDED_MODEL}\n")
+    print("Set NARROW_MCP_SELECTOR_PROVIDER=openrouter and OPENROUTER_API_KEY, and you're done --")
+    print(f"the tool defaults to {RECOMMENDED_MODEL} automatically once an OPENROUTER_API_KEY is set.\n")
+
+    try:
+        free_models = fetch_free_models()
+    except (urllib.error.URLError, TimeoutError, json.JSONDecodeError, OSError) as exc:
+        print(f"Could not fetch the live model list: {exc}", file=sys.stderr)
+        sys.exit(1)
+
+    if not free_models:
+        print("No individually-free models found right now (the meta-router above still works).")
+        return
+
+    print(f"Currently free, tool-calling-capable individual models ({len(free_models)}) --")
+    print("set NARROW_MCP_SELECTOR_MODEL=<id> to pick one specifically instead of the meta-router:\n")
+    id_width = max(len(m.get("id", "")) for m in free_models) + 2
+    print(f"{'id'.ljust(id_width)}context_length")
+    for m in sorted(free_models, key=lambda m: m.get("id", "")):
+        context_length = m.get("context_length", "?")
+        print(f"{m.get('id', '').ljust(id_width)}{context_length}")
+
+    print(
+        "\nNote: OpenRouter's free tier is rate-limited (20 req/min; 50 req/day, "
+        "or 1000/day once the account has $10+ lifetime spend)."
+    )
+
+
+if __name__ == "__main__":
+    main()

narrow_mcp-0.1.0/src/narrow_mcp/mcp_handler.py

@@ -0,0 +1,56 @@
+"""Thin MCP adapter. No business logic lives here -- it registers the one
+tool and calls straight into orchestrator.narrow_file, so the entire
+pipeline is testable via plain Python calls with zero MCP machinery
+involved.
+
+Verified against the installed `mcp` package (v2.2.0, 2026-07-28 spec) in
+this environment -- the v1 `FastMCP`/`@mcp.tool()` pattern referenced by
+older tutorials no longer exists in this SDK major version; it was renamed
+to `MCPServer` from `mcp.server.mcpserver`. If you're building against a
+different SDK version, re-check this against `mcp.server.mcpserver`'s own
+source before assuming this file's API calls still match.
+"""
+
+from __future__ import annotations
+
+from mcp.server.mcpserver import MCPServer
+
+from .config import Config
+from .models import ToolResult
+from .orchestrator import narrow_file as _narrow_file
+
+server = MCPServer(
+    "narrow-mcp",
+    instructions=(
+        "Narrows large, low-density non-source files (logs, build output, CSV, JSON, HTML) "
+        "down to the verbatim, line-numbered spans relevant to a stated intent -- verified "
+        "against the original file, never a summary. Refuses source code files; use "
+        "code-navigation tooling (LSP/tree-sitter/ast-grep) for those instead."
+    ),
+)
+
+
+@server.tool(
+    description=(
+        "Given a path to a large, low-density non-source file (logs, build output, CSV, JSON, "
+        "HTML) and a specific intent, returns only the verbatim line-numbered spans relevant to "
+        "that intent, verified against the original file -- never a summary. Refuses source code "
+        "files; use code-navigation tools for those."
+    )
+)
+def narrow_file(path: str, intent: str) -> ToolResult:
+    """path: absolute or workspace-relative path to the target file.
+
+    intent: a specific question or goal, e.g. 'why did this build fail' or
+    'rows with null customer_id'. Required -- not inferred from context.
+    """
+    config = Config.load()
+    return _narrow_file(path, intent, config)
+
+
+def main() -> None:
+    server.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()