ida-code 0.2.3__tar.gz → 0.2.4__tar.gz

{ida_code-0.2.3 → ida_code-0.2.4}/CHANGELOG.md

@@ -4,6 +4,17 @@ All notable changes to this project will be documented in this file.
 
 Format based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [0.2.4] - 2026-05-19
+
+### Added
+
+- **`get_guideline` tool** — tool-form companion to the `guidelines://*` resources. Same content, but tool listings are read more reliably than resource listings by cold LLM clients.
+
+### Changed
+
+- `search_docs` snippet cap is word-based (`max_snippet_length` → `max_snippet_words`, default 25). Avoids mid-word truncation and lines up better with token cost.
+- `search_docs` / `search_code` docstrings and the server `instructions` paragraph rewritten as discovery steers — `search_code` for API lookups, `search_docs` narrowed to HTML prose, both pointing at `get_guideline` / `get_source`.
+
 ## [0.2.3] - 2026-05-10
 
 ### Added

{ida_code-0.2.3 → ida_code-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ida-code
-Version: 0.2.3
+Version: 0.2.4
 Summary: MCP server for AI-assisted IDAPython scripting via idalib
 Project-URL: Homepage, https://github.com/Dil4rd/ida-code
 Project-URL: Repository, https://github.com/Dil4rd/ida-code
@@ -76,7 +76,7 @@ For other MCP clients, run the server directly:
 IDA_INSTALL_DIR=/opt/ida-pro-9.3 ida-code   # stdio transport
 ```
 
-## Tools (36)
+## Tools (37)
 
 Full parameter docs live in each tool's docstring — surfaced automatically to MCP clients via `tools/list`.
 
@@ -90,7 +90,7 @@ Full parameter docs live in each tool's docstring — surfaced automatically to
 | Snapshots | `list_snapshots`, `create_snapshot`, `restore_snapshot`, `delete_snapshot` |
 | Undo/redo | `get_undo_status`, `perform_undo`, `perform_redo` |
 | Inventory | `get_strings`, `get_imports`, `get_exports` |
-| Search | `search_docs`, `search_code`, `get_source` |
+| Search | `search_docs`, `search_code`, `get_source`, `get_guideline` |
 
 ## Resources & prompts
 

{ida_code-0.2.3 → ida_code-0.2.4}/README.md

@@ -47,7 +47,7 @@ For other MCP clients, run the server directly:
 IDA_INSTALL_DIR=/opt/ida-pro-9.3 ida-code   # stdio transport
 ```
 
-## Tools (36)
+## Tools (37)
 
 Full parameter docs live in each tool's docstring — surfaced automatically to MCP clients via `tools/list`.
 
@@ -61,7 +61,7 @@ Full parameter docs live in each tool's docstring — surfaced automatically to
 | Snapshots | `list_snapshots`, `create_snapshot`, `restore_snapshot`, `delete_snapshot` |
 | Undo/redo | `get_undo_status`, `perform_undo`, `perform_redo` |
 | Inventory | `get_strings`, `get_imports`, `get_exports` |
-| Search | `search_docs`, `search_code`, `get_source` |
+| Search | `search_docs`, `search_code`, `get_source`, `get_guideline` |
 
 ## Resources & prompts
 

{ida_code-0.2.3 → ida_code-0.2.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ida-code"
-version = "0.2.3"
+version = "0.2.4"
 description = "MCP server for AI-assisted IDAPython scripting via idalib"
 readme = "README.md"
 requires-python = ">=3.12"

{ida_code-0.2.3 → ida_code-0.2.4}/src/ida_code/code_search.py

@@ -725,7 +725,7 @@ def search(
 
     if include_docs:
         from ida_code.doc_search import search as _search_docs
-        doc_res = _search_docs(query, max_results=2, max_snippet_length=200, include_examples=False)
+        doc_res = _search_docs(query, max_results=2, max_snippet_words=30, include_examples=False)
         if doc_res.get("results"):
             out["related_docs"] = doc_res["results"]
 

{ida_code-0.2.3 → ida_code-0.2.4}/src/ida_code/doc_search.py

@@ -61,7 +61,7 @@ def _ensure_indexes():
 def search(
     query: str,
     max_results: int = 5,
-    max_snippet_length: int = 150,
+    max_snippet_words: int = 25,
     include_examples: bool = True,
 ) -> dict:
     """Search IDA HTML documentation. Returns a structured dict.
@@ -83,7 +83,7 @@ def search(
     for title, text, location in _html_docs:
         score = _score(terms, title, text)
         if score > 0:
-            snippet = _excerpt(text, terms, max_len=max_snippet_length)
+            snippet = _excerpt(text, terms, max_words=max_snippet_words)
             results.append((score, title, snippet, f"docs: {location}"))
 
     results.sort(key=lambda r: r[0], reverse=True)
@@ -138,31 +138,52 @@ def _score(terms: list[str], title: str, text: str) -> float:
     return total
 
 
-def _excerpt(text: str, terms: list[str], max_len: int = 300) -> str:
-    """Extract a snippet of *text* around the first matching term."""
+def _excerpt(text: str, terms: list[str], max_words: int = 25) -> str:
+    """Extract a word-bounded snippet of *text* around the first matching term.
+
+    Words are tokens produced by ``str.split()`` (whitespace-separated).
+    The snippet is at most ``max_words`` words plus optional ``"..."``
+    ellipses on each side when the window doesn't cover the whole text.
+    Cutting on word boundaries avoids mid-word truncation that char-based
+    capping produces, and the unit aligns more closely with token cost
+    than character count does.
+    """
     if not text:
         return ""
 
+    words = text.split()
+    if not words:
+        return ""
+
     lowered = text.lower()
-    best_pos = -1
+    best_char = -1
     for term in terms:
         pos = lowered.find(term)
-        if pos != -1 and (best_pos == -1 or pos < best_pos):
-            best_pos = pos
-
-    if best_pos == -1:
-        snippet = text[:max_len]
-    else:
-        half = max_len // 2
-        start = max(0, best_pos - half)
-        end = min(len(text), start + max_len)
-        if end - start < max_len:
-            start = max(0, end - max_len)
-        snippet = text[start:end]
-        if start > 0:
-            snippet = "..." + snippet
-        if end < len(text):
-            snippet = snippet + "..."
-
-    # Collapse whitespace for readability.
-    return " ".join(snippet.split())
+        if pos != -1 and (best_char == -1 or pos < best_char):
+            best_char = pos
+
+    # Locate which word index the best-match character lands in.
+    match_word_idx = 0
+    if best_char != -1:
+        # Re-tokenise on the same boundaries: walk words, tracking the
+        # original text offset by re-finding each word from the cursor.
+        cursor = 0
+        for i, w in enumerate(words):
+            cursor = text.find(w, cursor)
+            if cursor == -1 or cursor > best_char:
+                break
+            match_word_idx = i
+            cursor += len(w)
+
+    half = max_words // 2
+    start = max(0, match_word_idx - half)
+    end = min(len(words), start + max_words)
+    if end - start < max_words:
+        start = max(0, end - max_words)
+
+    snippet = " ".join(words[start:end])
+    if start > 0:
+        snippet = "..." + snippet
+    if end < len(words):
+        snippet = snippet + "..."
+    return snippet

{ida_code-0.2.3 → ida_code-0.2.4}/src/ida_code/prompts.py

@@ -91,9 +91,15 @@ return structured data, handle errors, and are faster to use.
 - **Use `execute` for custom analysis** — The `execute` tool gives you full \
 IDAPython access. Write custom scripts for pattern matching, data extraction, \
 or anything the dedicated tools don't cover.
-- **Search docs and examples** — Use `search_docs` to look up unfamiliar IDA \
-APIs. Use `search_examples` to find working IDAPython code patterns — it indexes \
-125 official examples with metadata, API usage, and source code.
+- **Search docs and code** — Use `search_docs` for IDA HTML documentation. \
+Use `search_code` to find Python source — library API definitions and \
+working example scripts in one query. Library entries show `def` signatures \
++ docstrings; example entries cover the in-IDA `python/examples` and the \
+standalone-idalib `idalib/examples` corpora. For "everything about func X", \
+a single `search_code("X")` call returns the API definition, example uses, \
+and cross-linked HTML docs. When a snippet is truncated, the result carries \
+`snippet_start_line` + `total_lines`; pass the same `file` to `get_source` \
+to fetch additional lines (sandboxed to the indexed corpora).
 - **Snapshot before bulk changes** — Call `create_snapshot` before renaming or \
 retyping many symbols. Use `restore_snapshot` to roll back if something goes wrong.
 - **Work incrementally** — Rename and retype a few variables, re-decompile, \
@@ -146,7 +152,11 @@ segment membership with `ida_segment.getseg(ea)` before accessing data.
 the final script.
 - The execution namespace persists — define helpers in one call and use \
 them in the next.
-- Use `search_docs` and `search_examples` to find API patterns.
+- Use `search_docs` for IDA HTML documentation. Use `search_code` for \
+Python source (API definitions + examples); set `docstring_only=True` \
+when searching by intent ("function that opens a database") rather than \
+identifier name. When a snippet is truncated, follow up with `get_source` \
+to fetch the rest from the same `file`.
 """
 
 

{ida_code-0.2.3 → ida_code-0.2.4}/src/ida_code/server.py

@@ -36,7 +36,14 @@ mcp = FastMCP(
         "annotate code, and run IDAPython scripts.\n\n"
         "Typical workflow: open_database → list_functions → decompile → "
         "annotate (rename_function, set_comment, set_variable) → iterate.\n\n"
-        "Only one database can be open at a time. Most tools require an open database."
+        "Only one database can be open at a time. Most tools require an open database.\n\n"
+        "Discovery: `guidelines://standalone_script`, `guidelines://plugin`, and "
+        "`guidelines://idapython_script` resources hold code templates and Hex-Rays "
+        "coding conventions — read whichever matches your task before writing. The "
+        "`reverse_engineer` and `create_script` prompts walk through full workflows. "
+        "For Python API signatures, idapro module, or example scripts use `search_code` "
+        "(then `get_source` to fetch more lines from any file it returns); "
+        "`search_docs` is HTML prose only (user-guide, developer-guide)."
     ),
 )
 
@@ -85,6 +92,11 @@ async def open_database(
     *arch* selects a specific architecture slice from a fat (universal) Mach-O
     binary (e.g. "arm64e", "x86_64"). Use list_architectures to discover
     available slices. Ignored for non-fat binaries.
+
+    Writing a standalone idalib script that calls this? First call
+    ``get_guideline("standalone_script")`` for the bootstrap template
+    (sys.path / IDADIR setup) and Hex-Rays coding conventions — those aren't
+    in this docstring.
     """
     open_path, original_path = session._prepare_open(path, arch, overwrite)
     return await on_ida_thread(
@@ -337,30 +349,32 @@ async def list_functions(offset: int = 0, limit: int = 50, name_filter: str = ""
     return await on_ida_thread(_impl)
 
 
-@mcp.tool
-def search_docs(
-    query: str,
-    max_results: int = 5,
-    max_snippet_length: int = 150,
-    include_examples: bool = True,
-) -> dict:
-    """Look up IDA HTML documentation. No database needs to be open.
+GuidelineTarget = Literal["standalone_script", "plugin", "idapython_script"]
 
-    Use this to find prose explanations, user-guide / developer-guide
-    chapters, and conceptual context.
 
-    For Python source — library API signatures (``ida_*.py``, ``idapro``)
-    and example scripts — use ``search_code`` instead.
-
-    Uses word-boundary matching: "set" matches "set_name" but not "reset".
-
-    When *include_examples* is True (default), also returns up to 2 matching
-    example scripts in the ``related_examples`` key (cross-linked from
-    ``search_code`` with ``kind="example"``).
-
-    *max_snippet_length* caps each snippet (default 150 chars).
+@mcp.tool
+def get_guideline(target: GuidelineTarget) -> str:
+    """Return the coding guideline for an IDA script type. No database needed.
+
+    Read this BEFORE writing any IDA Python code. Covers the bootstrap
+    template, key constraints (import order, single-thread, single-database),
+    Hex-Rays coding conventions (avoid `idc.py`/`idaapi`/`from X import Y`,
+    double-quote strings), and the search_code / search_docs / get_source
+    workflow for finding APIs and examples.
+
+    Targets:
+      - ``standalone_script`` — uses idalib outside IDA. sys.path setup,
+        ``import idapro`` first, ``open_database`` / ``close_database``.
+      - ``plugin`` — IDA plugin loaded inside the GUI. Subclass of
+        ``idaapi.plugin_t``, ``PLUGIN_ENTRY`` factory, hooks, actions.
+      - ``idapython_script`` — classic IDAPython script run via File >
+        Script File or the Python console. No bootstrap needed.
+
+    Identical content is also available as the MCP resource
+    ``guidelines://<target>``; the tool form is offered because tool listings
+    are read more reliably than resource listings by most MCP clients.
     """
-    return _search_docs(query, max_results, max_snippet_length, include_examples)
+    return _guidelines.get(target)
 
 
 CodeKind = Literal["library", "example", ""]
@@ -379,7 +393,12 @@ def search_code(
     max_snippet_line_chars: int = 200,
     include_docs: bool = True,
 ) -> dict:
-    """Find Python source — library APIs and/or example scripts. No database needs to be open.
+    """Find Python source — API signatures, idapro module, and example scripts.
+
+    **Primary tool for "what's the signature of X?" or "show me code that does Y"**
+    queries — covers `ida_*.py`, `idautils.py`, `idc.py`, the standalone idalib
+    `idapro` package, plus all in-IDA and idalib example scripts. No database
+    needs to be open.
 
     Unified search over:
 
@@ -436,6 +455,35 @@ def search_code(
     )
 
 
+@mcp.tool
+def search_docs(
+    query: str,
+    max_results: int = 5,
+    max_snippet_words: int = 25,
+    include_examples: bool = True,
+) -> dict:
+    """Look up IDA *HTML prose* documentation (user-guide / developer-guide).
+
+    **For Python API signatures, idapro module, or example scripts, use
+    `search_code` instead** — this tool only indexes the HTML docs, not
+    Python source. No database needs to be open.
+
+    Use this for conceptual context and chapter-style explanations:
+    "what is auto-analysis", "how does the structure editor work", etc.
+
+    Uses word-boundary matching: "set" matches "set_name" but not "reset".
+
+    When *include_examples* is True (default), also returns up to 2 matching
+    example scripts in the ``related_examples`` key (cross-linked from
+    ``search_code`` with ``kind="example"``).
+
+    *max_snippet_words* caps each snippet at this many whitespace-separated
+    words (default 25). Word-based cap avoids mid-word truncation and aligns
+    more closely with LLM token cost than character cap.
+    """
+    return _search_docs(query, max_results, max_snippet_words, include_examples)
+
+
 @mcp.tool
 def get_source(file: str, start_line: int = 1, line_count: int = 200) -> dict:
     """Read a slice of a Python file from the indexed corpora. No database needed.

{ida_code-0.2.3 → ida_code-0.2.4}/tests/test_doc_search.py

@@ -82,33 +82,38 @@ class TestScore:
 
 class TestExcerpt:
     def test_short_text_returned_fully(self):
-        result = _excerpt("hello world", ["hello"], max_len=300)
+        result = _excerpt("hello world", ["hello"], max_words=10)
         assert "hello world" in result
 
     def test_excerpt_around_match(self):
-        text = "A" * 200 + " TARGET " + "B" * 200
-        result = _excerpt(text, ["target"], max_len=100)
+        text = " ".join(["before"] * 30 + ["TARGET"] + ["after"] * 30)
+        result = _excerpt(text, ["target"], max_words=10)
         assert "TARGET" in result
-        assert len(result) < 200  # much shorter than original
+        assert len(result.split()) <= 11  # 10 words + maybe ellipsis tokens
 
     def test_ellipsis_at_start(self):
-        text = "A" * 200 + "match" + "B" * 200
-        result = _excerpt(text, ["match"], max_len=100)
+        text = " ".join(["before"] * 50 + ["MATCH"] + ["after"] * 50)
+        result = _excerpt(text, ["match"], max_words=5)
         assert result.startswith("...")
 
     def test_ellipsis_at_end(self):
-        text = "A" * 200 + "match" + "B" * 200
-        result = _excerpt(text, ["match"], max_len=100)
+        text = " ".join(["before"] * 50 + ["MATCH"] + ["after"] * 50)
+        result = _excerpt(text, ["match"], max_words=5)
         assert result.endswith("...")
 
     def test_no_match_returns_beginning(self):
         text = "start of text and more"
-        result = _excerpt(text, ["nonexistent"], max_len=300)
+        result = _excerpt(text, ["nonexistent"], max_words=50)
         assert "start" in result
 
-    def test_whitespace_collapsed(self):
-        result = _excerpt("foo   \n\n   bar", ["foo"], max_len=300)
-        assert "  " not in result
+    def test_word_boundary_no_midword_cut(self):
+        """Truncation lands on whole words, never mid-word."""
+        text = " ".join(["alphabet"] * 100)
+        result = _excerpt(text, ["alphabet"], max_words=5)
+        # Strip ellipses, every remaining word should be the full "alphabet"
+        body = result.replace("...", "").strip()
+        for word in body.split():
+            assert word == "alphabet", f"got partial word: {word!r}"
 
 
 class TestSearchCrossLinking: