# TallyMCP — Complete Machine-Readable Agent & Developer Specification
> Full LLM Agent Context Document
> Version: 1.0.0 | MCP Protocol: 2024-11-05 | Transport: stdio / JSON-RPC 2.0
> Repository: https://github.com/Shivvam/tallyprimemcp
> Portal: https://tallymcp.vercel.app/

---

## 1. System Architecture & Boundaries

```text
┌────────────────────────────────────────────────────────────────┐
│                       YOUR LOCAL WORKSTATION                   │
│                                                                │
│  ┌───────────────────────────┐      JSON-RPC 2.0 (stdio)       │
│  │     AI Agent Client       │ ◄────────────────────────────►  │
│  │ (Claude / Cursor / Wind.) │        stdin / stdout           │
│  └───────────────────────────┘                                 │
│                 │                                              │
│                 ▼                                              │
│  ┌───────────────────────────┐                                 │
│  │    tally-mcp (Rust)       │ ◄──── Token Approval (HTTP)     │
│  │   - Validation Engine     │       http://127.0.0.1:9190     │
│  │   - Journal & WAL         │       [HUMAN CLICK REQUIRED]    │
│  │   - XML Encoder/Decoder   │                                 │
│  └──────────────┬────────────┘                                 │
│                 │ Native XML-over-HTTP                         │
│                 │ http://127.0.0.1:9000 (Loopback or LAN)      │
│                 ▼                                              │
│  ┌───────────────────────────┐                                 │
│  │      TallyPrime           │                                 │
│  │    (Company Books)        │                                 │
│  └───────────────────────────┘                                 │
└────────────────────────────────────────────────────────────────┘
```

### Safety & Invariants
1. **Write Isolation:** No MCP tool can commit transactions directly to Tally. All write attempts MUST go through `tally_draft_voucher`.
2. **Human In The Loop:** A voucher draft produces a local cryptographic HMAC URL on `http://127.0.0.1:9190/approve?token=...`. The transaction is ONLY committed when the human user opens that URL and clicks "Approve".
3. **Double-Entry Validation:** Every voucher draft must balance:
   $$\sum \text{Debits} + \sum \text{Credits} = 0$$
   Unbalanced vouchers are rejected by the validator before any draft is created.
4. **Idempotency & Fingerprinting:** Vouchers are fingerprinted via SHA-256 hash of their contents (`company + date + number + party + entries`). Staging identical vouchers results in duplicate detection.
5. **Deterministic Outputs:** Tally report responses (such as Day Book transactions) are parsed using `quick-xml` into clean, deterministic JSON objects. Empty report envelopes return explicit notices rather than raw empty XML tags.

---

## 2. MCP JSON-RPC 2.0 Protocol Details

### Stdio Transport Specifications
- Process spawn: `tally-mcp serve`
- `stdin`: Receives standard JSON-RPC 2.0 requests.
- `stdout`: Emits ONLY standard JSON-RPC 2.0 responses. Zero unsolicited log lines are sent to stdout.
- `stderr`: Emits diagnostic trace logs (e.g. `[INFO]`, `[DEBUG]` when `TALLY_DEBUG=1`).

---

## 3. Complete MCP Tools Reference

### Tool 1: `tally_status`
- **Access:** `read`
- **Description:** Checks Tally reachability, circuit breaker state, active company, and roundtrip latency.
- **Input Schema:**
```json
{
  "type": "object",
  "properties": {}
}
```
- **Example Response:**
```json
{
  "status": "online",
  "reachable": true,
  "target_url": "http://127.0.0.1:9000",
  "circuit_breaker": "Closed",
  "write_mode": "approve",
  "active_company": "Acme Trading Pvt Ltd",
  "loaded_companies": ["Acme Trading Pvt Ltd", "Beta Logistics"],
  "latency_ms": 4
}
```

---

### Tool 2: `tally_list_companies`
- **Access:** `read`
- **Description:** Returns all company books currently open or available in TallyPrime.
- **Input Schema:**
```json
{
  "type": "object",
  "properties": {}
}
```
- **Example Response:**
```json
[
  "Acme Trading Pvt Ltd",
  "Beta Logistics LLP"
]
```

---

### Tool 3: `tally_set_active_company`
- **Access:** `session`
- **Description:** Sets the active target company for all subsequent queries in the current session.
- **Input Schema:**
```json
{
  "type": "object",
  "properties": {
    "company": {
      "type": "string",
      "description": "The exact name of the company loaded in Tally"
    }
  },
  "required": ["company"]
}
```
- **Example Response:**
```json
{
  "success": true,
  "active_company": "Acme Trading Pvt Ltd"
}
```

---

### Tool 4: `tally_list_ledgers`
- **Access:** `read`
- **Description:** Lists all ledger account names available in the active or specified company.
- **Input Schema:**
```json
{
  "type": "object",
  "properties": {
    "company": {
      "type": "string",
      "description": "Company name (optional if active company is set)"
    }
  }
}
```
- **Example Response:**
```json
[
  "Bank Account - HDFC",
  "Cash",
  "Electricity Expense",
  "Office Rent",
  "Sales Account - GST 18%",
  "Sundry Creditors - Acme Suppliers",
  "Sundry Debtors - Globex Corp"
]
```

---

### Tool 5: `tally_trial_balance`
- **Access:** `read`
- **Description:** Exports the Trial Balance report from TallyPrime for a specified period.
- **Input Schema:**
```json
{
  "type": "object",
  "properties": {
    "company": {
      "type": "string",
      "description": "Company name (optional if active company set)"
    },
    "from_date": {
      "type": "string",
      "description": "Start date in YYYYMMDD format (e.g. 20250401)"
    },
    "to_date": {
      "type": "string",
      "description": "End date in YYYYMMDD format (e.g. 20250430)"
    }
  }
}
```

---

### Tool 6: `tally_day_book`
- **Access:** `read`
- **Description:** Exports Day Book transaction vouchers formatted deterministically as structured JSON.
- **Input Schema:**
```json
{
  "type": "object",
  "properties": {
    "company": {
      "type": "string",
      "description": "Company name"
    },
    "from_date": {
      "type": "string",
      "description": "Start date in YYYYMMDD format"
    },
    "to_date": {
      "type": "string",
      "description": "End date in YYYYMMDD format"
    }
  }
}
```
- **Deterministic Response Format:**
```json
[
  {
    "date": "2025-04-15",
    "voucher_type": "Payment",
    "voucher_number": "PV-2025-004",
    "party": "Tata Power",
    "amount": 12500.00,
    "is_cancelled": false,
    "narration": "Electricity bill payment for March 2025",
    "ledger_entries": [
      {
        "ledger": "Electricity Expense",
        "amount": 12500.00
      },
      {
        "ledger": "Bank Account - HDFC",
        "amount": -12500.00
      }
    ]
  }
]
```
*Note: If no records match, TallyMCP returns: `"No vouchers found in Day Book for the selected company and period (empty report envelope)."`*

---

### Tool 7: `tally_draft_voucher`
- **Access:** `draft`
- **Description:** Validates debit/credit balance, performs duplicate checks, and stages a voucher draft. Returns an approval URL for the human user.
- **Input Schema:**
```json
{
  "type": "object",
  "properties": {
    "company": { "type": "string", "description": "Target company name" },
    "voucher_type": { "type": "string", "description": "Purchase, Sales, Journal, Payment, or Receipt" },
    "date": { "type": "string", "description": "Date in YYYYMMDD format" },
    "number": { "type": "string", "description": "Voucher or invoice number" },
    "party_ledger": { "type": "string", "description": "Party ledger name" },
    "entries": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "ledger": { "type": "string" },
          "amount": { "type": "string", "description": "Amount as decimal string. Sum must balance to 0.00." }
        },
        "required": ["ledger", "amount"]
      }
    },
    "narration": { "type": "string", "description": "Narration text" }
  },
  "required": ["company", "voucher_type", "date", "number", "party_ledger", "entries"]
}
```
- **Example Response:**
```json
{
  "status": "staged",
  "draft_id": "d_e3b0c44298fc1c14",
  "approval_url": "http://127.0.0.1:9190/approve?token=tok_91a029fe8",
  "expires_in_secs": 900,
  "summary": {
    "voucher_type": "Payment",
    "total_amount": 12500.00,
    "balanced": true
  },
  "message": "Draft created successfully. Direct the human user to the approval URL to commit."
}
```

---

### Tool 8: `tally_preview_draft`
- **Access:** `read`
- **Description:** Returns formatted summary and exact XML envelope of a staged draft before approval.
- **Input Schema:**
```json
{
  "type": "object",
  "properties": {
    "draft_id": { "type": "string", "description": "Draft ID" }
  },
  "required": ["draft_id"]
}
```

---

### Tool 9: `tally_commit_draft`
- **Access:** `write`
- **Description:** Posts an approved voucher draft to Tally. (Requires authorization token from user approval).
- **Input Schema:**
```json
{
  "type": "object",
  "properties": {
    "draft_id": { "type": "string", "description": "Draft ID" }
  },
  "required": ["draft_id"]
}
```

---

### Tool 10: `tally_discard_draft`
- **Access:** `draft`
- **Description:** Cancels and deletes an unapproved voucher draft.
- **Input Schema:**
```json
{
  "type": "object",
  "properties": {
    "draft_id": { "type": "string", "description": "Draft ID" }
  },
  "required": ["draft_id"]
}
```

---

### Tool 11: `tally_extract_document`
- **Access:** `read/ai`
- **Description:** Extracts structured accounting data (vendor, invoice date, line items, taxes, totals) from a local PDF or image invoice.
- **Input Schema:**
```json
{
  "type": "object",
  "properties": {
    "file_path": { "type": "string", "description": "Absolute path to local PDF or image invoice" }
  },
  "required": ["file_path"]
}
```

---

### Tool 12: `tally_run_report`
- **Access:** `read`
- **Description:** Runs an extensible TDL pack report (e.g. `outstanding_ageing`, `gstr_summary`).
- **Input Schema:**
```json
{
  "type": "object",
  "properties": {
    "report_name": { "type": "string", "description": "Report identifier" },
    "parameters": { "type": "object", "description": "Report template arguments" }
  },
  "required": ["report_name"]
}
```

---

## 4. Multi-Turn Agent Workflow Guide

When a human user asks:
*"What were our sales transactions today, and draft a payment of ₹15,000 to Apex Supplies from our HDFC bank?"*

### Recommended Agent Execution Path:
1. Call `tally_list_companies` to verify loaded company name.
2. Call `tally_set_active_company` with the company name.
3. Call `tally_day_book` with today's date formatted as `YYYYMMDD`.
4. Parse the structured JSON response and summarize sales vouchers for the user.
5. Call `tally_list_ledgers` to verify exact ledger names (`Apex Supplies`, `Bank Account - HDFC`).
6. Call `tally_draft_voucher` with:
   - `voucher_type`: `"Payment"`
   - `entries`:
     - `{"ledger": "Apex Supplies", "amount": "15000.00"}`
     - `{"ledger": "Bank Account - HDFC", "amount": "-15000.00"}`
7. Receive `draft_id` and `approval_url`.
8. Provide the user with:
   - The sales summary.
   - The drafted voucher details.
   - **The approval link** to open in their browser: `http://127.0.0.1:9190/approve?token=...`
   - Clearly state: *"The voucher has been staged locally. Please click the approval link to inspect and confirm the entry into Tally."*

---

## 5. CLI Reference & Troubleshooting

| Command | Purpose |
|---|---|
| `tally-mcp doctor [--show-names]` | Verifies Tally HTTP port 9000, active company, and PATH. |
| `tally-mcp setup` | Configures Claude Desktop, Cursor, and Windsurf automatically. |
| `tally-mcp serve [--host <IP>] [--port <PORT>]` | Runs stdio MCP server for AI clients. |
| `tally-mcp ui [--ui-port <PORT>]` | Runs local companion dashboard with live MCP tool testing. |
| `tally-mcp cleanup [--dry-run]` | Cleans temporary logs, cache, and staged drafts safely. |
| `tally-mcp uninstall` | Fully removes all local TallyMCP data, PATH, and shortcuts. |