diaphora-mcp

[रूसी संस्करण](https://github.com/xteardx/diaphora-mcp/blob/master/README.ru.md)

# Diaphora MCP

अपने AI सहायक से दो IDA-विश्लेषित बाइनरी की तुलना करें। Diaphora MCP सहेजे गए IDA डेटाबेस को निर्यात करता है, [Diaphora](https://github.com/joxeankoret/diaphora) चलाता है, और AI को संबंधित फ़ंक्शन और उनके कॉल ग्राफ़ का निरीक्षण करने देता है।

डिफ़ॉल्ट इंटरफ़ेस में तुलना पर केंद्रित **10 टूल** हैं। Diaphora मिलान प्रदान करता है; AI वास्तविक कोड पढ़ता है और परिवर्तनों की व्याख्या करता है।

[त्वरित शुरुआत](#quick-start) · [उदाहरण](#examples) · [टूल](#tools) · [समस्या निवारण](#troubleshooting)

```text
old.i64 + new.i64 → headless export → SQLite exports + diff results
                                       ↓
                            summary → matched code → call graph
```

## आवश्यकताएँ

- Python 3.10+, `idat.exe`/`idat64` के साथ IDA Pro, और एक इंस्टॉल किया गया Diaphora प्लगइन।
- दोनों बाइनरी का विश्लेषण किया गया हो और `.i64`/`.idb` डेटाबेस के रूप में सहेजा गया हो।
- एक स्थानीय MCP क्लाइंट, जैसे Codex, Claude Code या Cursor।
- एक संगत Hex-Rays डीकंपाइलर केवल तभी यदि आप pseudocode चाहते हैं।

IDA और Diaphora अलग-अलग इंस्टॉल किए जाते हैं। Diff-schema सत्यापन वर्तमान में Diaphora **3.4.1** को लक्षित करता है; अन्य स्कीमाओं के लिए संगतता अपडेट की आवश्यकता हो सकती है। Diff के लिए उपयोग किए जाने वाले Python इंटरप्रेटर में Diaphora की standalone निर्भरताएँ इंस्टॉल होनी चाहिए।

## त्वरित शुरुआत

### 1. इंस्टॉल करें और एक आउटपुट डायरेक्टरी बनाएँ

```powershell
git clone https://github.com/xTeardx/diaphora-mcp.git
cd diaphora-mcp
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e .
New-Item -ItemType Directory -Force C:\diaphora-outputs | Out-Null
```

### 2. MCP सर्वर कनेक्ट करें

अपने क्लाइंट के MCP कॉन्फ़िगरेशन में यह प्रविष्टि जोड़ें। रिपॉज़िटरी, IDA और Diaphora पथों को अपने इंस्टॉलेशन पथों से बदलें। उस वातावरण से Python executable का उपयोग करें जहाँ आपने यह प्रोजेक्ट इंस्टॉल किया है।

```json
{
  "mcpServers": {
    "diaphora": {
      "command": "C:/src/diaphora-mcp/.venv/Scripts/python.exe",
      "args": ["C:/src/diaphora-mcp/diaphora_mcp_server.py"],
      "env": {
        "IDAT_PATH": "C:/Program Files/IDA Professional 9.3/idat.exe",
        "DIAPHORA_DIR": "C:/Program Files/IDA Professional 9.3/plugins/diaphora",
        "DIAPHORA_OUTPUT_ROOT": "C:/diaphora-outputs"
      }
    }
  }
}
```

क्लाइंट stdio के माध्यम से सर्वर लॉन्च करता है; शुरू करने के लिए कोई अलग वेब सेवा नहीं है। इसके कोड या वातावरण बदलने के बाद MCP सर्वर को पुनः आरंभ करें। एक सफल कनेक्शन नीचे सूचीबद्ध 10 टूल को उजागर करता है।

### 3. अपने सहायक से फ़ाइलों की तुलना करने के लिए कहें

```text
Use Diaphora to compare C:/analysis/old.i64 (old) against
C:/analysis/new.i64 (new). Save output under C:/diaphora-outputs/run-001.
Export headlessly with assembly detail, keep the exports, show a summary,
then inspect partial matches and explain the code changes in the interesting
functions. Use the result mapping when comparing functions and call graphs.
```

हर बार एक **नई run डायरेक्टरी** चुनें। मौजूदा जनरेट किए गए लक्ष्यों को कभी अधिलेखित नहीं किया जाता।

## उदाहरण

निम्नलिखित JSON ब्लॉक **MCP टूल आर्गुमेंट** हैं, शेल कमांड नहीं। आपका सहायक नामित टूल को सीधे कॉल कर सकता है। पथ और `0x401000` उदाहरण हैं; अपने स्वयं के run द्वारा लौटाए गए पथ और पते का उपयोग करें।

### 1. दो IDA डेटाबेस निर्यात करें और तुलना करें

टूल: **`batch_export_and_diff`**। Old हमेशा पहला इनपुट होता है, new दूसरा।

```json
{
  "idb1_path": "C:/analysis/old.i64",
  "idb2_path": "C:/analysis/new.i64",
  "output_dir": "C:/diaphora-outputs/run-001",
  "export_mode": "headless",
  "use_decompiler": false,
  "summaries_only": false,
  "cleanup": false,
  "limit": 100,
  "unmatched_limit": 50
}
```

यह Hex-Rays की आवश्यकता के बिना assembly विवरण रखता है। अपनी आवश्यकता का export प्रोफ़ाइल चुनें:

| विवरण | `use_decompiler` | `summaries_only` | उपयोग |
| --- | --- | --- | --- |
| Matching summaries | `false` | `true` | तेज़ पहला पास; कोई विस्तृत कोड नहीं |
| Assembly | `false` | `false` | डीकंपाइलर के बिना disassembly की तुलना करें |
| Assembly + pseudocode | `true` | `false` | संगत Hex-Rays डीकंपाइलर के साथ कोड समीक्षा; धीमा |

हमेशा प्रतिक्रिया से आउटपुट पथ लें:

```text
OLD_SQLITE = steps.export1.output
NEW_SQLITE = steps.export2.output
RESULTS    = steps.diff.output
```

इस उदाहरण के लिए, जनरेट की गई फ़ाइलें `run-001` के अंतर्गत `old.diaphora.sqlite`, `new.diaphora.sqlite`, और `old_vs_new.diaphora` हैं। समान इनपुट basenames अलग `old_`/`new_` export नाम उत्पन्न करते हैं। बाद में फ़ंक्शन निरीक्षण के लिए `cleanup=false` रखें।

### 2. सारांश प्राप्त करें और परिवर्तित मिलानों का निरीक्षण करें

टूल: **`get_diff_summary`**।

```json
{
  "results_path": "C:/diaphora-outputs/run-001/old_vs_new.diaphora"
}
```

टूल: **`get_diff_results`**। यह पृष्ठ कम-अनुपात वाले आंशिक मिलानों से शुरू होता है।

```json
{
  "results_path": "C:/diaphora-outputs/run-001/old_vs_new.diaphora",
  "match_type": "partial",
  "min_ratio": 0.0,
  "limit": 50,
  "offset": 0,
  "unmatched_limit": 50,
  "unmatched_offset": 0,
  "sort_by": "ratio",
  "sort_order": "asc"
}
```

`partial` एक Diaphora मिलान श्रेणी चुनता है, व्यवहारिक परिवर्तन की गारंटी नहीं। सभी समर्थित श्रेणियों के लिए `match_type="all"` का उपयोग करें। प्रतिक्रिया में श्रेणी गणना, फ़िल्टर किया गया कुल, मिलान, unmatched पंक्तियाँ, `next_offset` और `next_unmatched_offset` शामिल हैं।

जारी रखने के लिए, लौटाए गए next offsets को अगली कॉल में कॉपी करें, समान फ़िल्टर और सॉर्ट रखते हुए। उदाहरण के लिए, यदि वे `50` और `50` हैं, तो `offset=50` और `unmatched_offset=50` का उपयोग करें। `null` next offset का अर्थ है कि वह सूची समाप्त हो गई है; उसे आगे बढ़ाना बंद करें। दोनों सूचियाँ स्वतंत्र रूप से आगे बढ़ती हैं। पृष्ठ आकार सकारात्मक होने चाहिए और 5000 पर सीमित हैं। सबसे मजबूत मिलानों को पहले देखने के लिए `sort_order="desc"` का उपयोग करें।

### 3. एक मिलान किए गए फ़ंक्शन और उसके ग्राफ़ की तुलना करें

टूल: **`compare_functions`**।

```json
{
  "db1_path": "C:/diaphora-outputs/run-001/old.diaphora.sqlite",
  "db2_path": "C:/diaphora-outputs/run-001/new.diaphora.sqlite",
  "address": "0x401000",
  "match_results_path": "C:/diaphora-outputs/run-001/old_vs_new.diaphora"
}
```

प्रतिक्रिया में `function_old`, `function_new`, उपलब्ध assembly/pseudocode, मापे गए अंतर, और identity साक्ष्य शामिल हैं। आप `address` के बजाय `name` का उपयोग कर सकते हैं। यदि दोनों सेलेक्टर प्रदान किए जाते हैं, तो address को प्राथमिकता मिलती है; नाम से चयन करते समय इसे छोड़ दें।

टूल: **`get_changed_callgraph`** उपरोक्त समान आर्गुमेंट स्वीकार करता है। यह परिवर्तनों की रिपोर्ट करने से पहले संबंधित caller/callee पतों का अनुवाद करता है, और अनसुलझे पड़ोसियों को पुष्ट किए गए edge अंतरों से अलग करता है।

हेक्साडेसिमल इनपुट को स्पष्ट बनाने के लिए **`0x`-प्रीफ़िक्स्ड पतों** को प्राथमिकता दें। उपलब्ध होने पर `match_results_path` प्रदान करें: यह rebasing और नाम बदले गए फ़ंक्शन को संभालता है। अकेले समान पते identity स्थापित नहीं करते। अस्पष्ट या अनुपलब्ध मिलान विलोपन कहे जाने के बजाय अनसुलझे रहते हैं। यदि आपने मैन्युअल रूप से एक जोड़ी सत्यापित की है, तो आप स्पष्ट रूप से `address2` या `name2` प्रदान कर सकते हैं।

### 4. एक फ़ंक्शन खोजें और उसका कोड पढ़ें

टूल: **`search_export_db`**। `name_pattern` SQL LIKE का उपयोग करता है: `%` किसी भी अनुक्रम से मेल खाता है।

```json
{
  "db_path": "C:/diaphora-outputs/run-001/old.diaphora.sqlite",
  "name_pattern": "%parse%",
  "min_instructions": 20,
  "limit": 20
}
```

टूल: **`get_function_pseudocode`** अपने नाम के बावजूद उपलब्ध pseudocode **और assembly** लौटाता है।

```json
{
  "db_path": "C:/diaphora-outputs/run-001/old.diaphora.sqlite",
  "address": "0x401000"
}
```

यदि pseudocode खाली है, तो एक संगत डीकंपाइलर का उपयोग करके `use_decompiler=true` और `summaries_only=false` के साथ एक नई run डायरेक्टरी में export को फिर से चलाएँ। export मेटाडेटा का निरीक्षण करने के लिए `db_path` के साथ `get_export_info` का उपयोग करें।

### 5. आपके पास पहले से मौजूद exports की तुलना करें

टूल: **`diff_diaphora_dbs`**। यह IDA export को छोड़ देता है और मौजूदा आधिकारिक SQLite exports की तुलना करता है।

```json
{
  "db1_path": "C:/diaphora-outputs/run-001/old.diaphora.sqlite",
  "db2_path": "C:/diaphora-outputs/run-001/new.diaphora.sqlite",
  "output_path": "C:/diaphora-outputs/another-diff.diaphora"
}
```

एक नए export के लिए, `idb_path`, एक नई `output_path`, और `export_mode="headless"` के साथ `export_idb_to_diaphora` का उपयोग करें।

## टूल

| टूल | उद्देश्य |
| --- | --- |
| `export_idb_to_diaphora` | एक सहेजे गए IDA डेटाबेस को निर्यात करें |
| `batch_export_and_diff` | दोनों डेटाबेस निर्यात करें और उनकी तुलना करें |
| `diff_diaphora_dbs` | मौजूदा exports की तुलना करें |
| `get_diff_summary` | मिलान आँकड़े और सीमित उदाहरण |
| `get_diff_results` | फ़िल्टर किए गए, सॉर्ट किए गए, पृष्ठांकित परिणाम |
| `get_export_info` | export मेटाडेटा और गणना |
| `search_export_db` | फ़ंक्शन खोजें |
| `get_function_pseudocode` | assembly/pseudocode पढ़ें |
| `compare_functions` | एक हल किए गए old/new जोड़ी की तुलना करें |
| `get_changed_callgraph` | मैप किए गए callers/callees की तुलना करें |

सटीक हस्ताक्षर MCP `tools/list` के माध्यम से खोजे जा सकते हैं। देखें [टूल संदर्भ](https://github.com/xteardx/diaphora-mcp/blob/master/docs/TOOLS.md)।

## Export मोड और कॉन्फ़िगरेशन

| मोड | व्यवहार |
| --- | --- |
| `headless` | IDA को headlessly लॉन्च करें और diff schema को मान्य करें; तुलना के लिए अनुशंसित |
| `auto` | सक्रिय GUI bridge का प्रयास करें, फिर headless fallback |
| `gui` | सही खुले GUI सत्र की आवश्यकता है; कोई headless fallback नहीं |

`batch_export_and_diff` के लिए `headless` आवश्यक है।

| पर्यावरण चर | अर्थ |
| --- | --- |
| `IDAT_PATH` | IDA headless executable का पूर्ण पथ |
| `DIAPHORA_DIR` | Diaphora स्क्रिप्ट वाली डायरेक्टरी |
| `DIAPHORA_OUTPUT_ROOT` | नए exports और diff परिणामों के लिए मौजूदा अनुमत root |
| `DIAPHORA_PYTHON` | वैकल्पिक diff इंटरप्रेटर; डिफ़ॉल्ट रूप से MCP सर्वर का इंटरप्रेटर |
| `DIAPHORA_ENABLE_LEGACY_TOOLS` | ठीक `1` पिछले 21-टूल इंटरफ़ेस को सक्षम करता है |

Legacy matching, feature scores, security triage, रिपोर्ट, मेटाडेटा और डायग्नोस्टिक्स opt-in बने हुए हैं। उन्हें सक्षम करने के लिए, कॉन्फ़िगरेशन के `env` ऑब्जेक्ट में निम्नलिखित प्रविष्टि जोड़ें और पुनः आरंभ करें:

```json
{
  "DIAPHORA_ENABLE_LEGACY_TOOLS": "1"
}
```

ये टूल heuristics का उपयोग करते हैं; उनके स्कोर semantic equivalence, security fixes या causation साबित नहीं करते। [कॉन्फ़िगरेशन](https://github.com/xteardx/diaphora-mcp/blob/master/docs/CONFIGURATION.md) · [GUI सेटअप](https://github.com/xteardx/diaphora-mcp/blob/master/GUI_INSTRUCTIONS.md)।

## समस्या निवारण

| लक्षण | कार्रवाई |
| --- | --- |
| लक्ष्य पहले से मौजूद है | एक नई run डायरेक्टरी या आउटपुट फ़ाइलनाम का उपयोग करें |
| अनुमत root के बाहर आउटपुट | `DIAPHORA_OUTPUT_ROOT` के अंतर्गत एक गंतव्य चुनें; पहले root बनाएँ |
| परिणाम टूल को IDA डेटाबेस पास किया गया | उपयुक्त रूप से लौटाए गए `.diaphora.sqlite` exports या `.diaphora` परिणामों का उपयोग करें |
| अनुपलब्ध/अस्पष्ट समकक्ष | old/new क्रम और मैपिंग जाँचें; उम्मीदवार का मैन्युअल रूप से निरीक्षण करें |
| खाली assembly/pseudocode | export प्रोफ़ाइल जाँचें; एक नया विस्तृत export प्राप्त करें |
| Export/diff में लंबा समय लगता है | MCP क्लाइंट timeout बढ़ाएँ; स्थानीय `logs/` का निरीक्षण करें; summaries-only पहले पास पर विचार करें |
| IDB एक IDA सत्र द्वारा लॉक है | सत्र बंद करें या एकल export के लिए मेल खाते GUI export मोड का उपयोग करें |
| असमर्थित schema | समर्थित Diaphora संस्करण के साथ पुनः export करें; रिपोर्ट किए गए अनुपलब्ध tables/columns देखें |

Matching heuristic बनी हुई है; उच्च अनुपात साक्ष्य है, प्रमाण नहीं। Unmatched फ़ंक्शन पुष्ट additions/deletions नहीं हैं। बाइनरी, IDBs, exports और logs को Git से बाहर रखें। देखें [वर्कफ़्लो](https://github.com/xteardx/diaphora-mcp/blob/master/docs/WORKFLOWS.md), [सीमाएँ](https://github.com/xteardx/diaphora-mcp/blob/master/docs/LIMITATIONS.md), और [सुरक्षा](https://github.com/xteardx/diaphora-mcp/blob/master/SECURITY.md)।

## विकास

```powershell
.\.venv\Scripts\python.exe -m pip install -e ".[dev]"
.\.venv\Scripts\python.exe -m pytest -q
.\.venv\Scripts\python.exe -m compileall -q .
git diff --check
```

रिग्रेशन सूट सिंथेटिक डेटाबेस और mocked IDA प्रक्रियाओं का उपयोग करता है। वास्तविक IDA export के लिए स्थानीय एकीकरण सत्यापन आवश्यक है। [योगदान](https://github.com/xteardx/diaphora-mcp/blob/master/CONTRIBUTING.md) · [एजेंट निर्देश](https://github.com/xteardx/diaphora-mcp/blob/master/AGENTS.md)।