Metadata-Version: 2.4
Name: hank-excel-mcp
Version: 0.2.0
Summary: Excel read clients, MCP server, relay backend, and tool registry
License: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: fastapi
Requires-Dist: uvicorn
Requires-Dist: httpx<0.29,>=0.27
Requires-Dist: fastmcp<5,>=4
Requires-Dist: mcp<3,>=2
Requires-Dist: python-dotenv
Requires-Dist: cryptography>=42

# hank-excel-mcp

Python package for connecting Excel to AI via MCP.

See the [main README](../README.md) for full documentation.

## Install

Install this source revision from this directory:

```bash
pip install .
```

The distribution is `hank-excel-mcp`; the Python import remains `excel_mcp`
and the console command remains `excel-mcp`. For package development, use
`pip install -e .` instead. The read client is part of source version 0.2.0;
this does not assert that version has been published to a package index.

## Components

- `excel_mcp.mcp_server` — MCP stdio server (`python -m excel_mcp`)
- `excel_mcp.relay` — relay state and `create_relay_app()` factory; an embedding
  application must supply request authentication
- `excel_mcp.tool_registry` — built-in workbook tools plus `register_tools()` extensibility
- `excel_mcp.mcp_server.channel_status` — relay/taskpane health and recovery inspection
- `excel_mcp.client` — `ExcelClient` and its injectable `ExcelTransport` protocol
- `excel_mcp.views` — typed dictionary views of the existing read responses

The live MCP server exposes `channel_status` plus the registry-backed workbook
tools. Inspect the registered surface in process when changing either owner.

`excel-mcp start` is a host-repository convenience command that launches
`api.main:app`; it is not a standalone authenticated relay. Portable consumers
should embed `create_relay_app()` with their own request authenticator.

## Composable reads

`from excel_mcp import ExcelClient, ExcelTransport` imports the client without
starting or importing the MCP server or relay. The embedding host supplies a
transport implementing `call`, `search`, and `describe`; the client contains no
credentials, session discovery, or independent operation grants.

`ExcelClient` exposes `read_cells`, `get_used_range`, `list_sheets`,
`read_range_csv`, `read_sheet_csv`, and `find_cells`. Every read requires the
current workbook session token through `workbook`; sheet-scoped reads also
require `sheet_name`. The client forwards that token as the existing `_workbook`
argument. Worksheet enumeration indexes and active-sheet observations are not
durable targeting identities.

Responses remain the producer's dictionaries, including additional provenance
and CSV coverage/continuation metadata. `get_used_range` preserves `None` for
an empty sheet; `read_cells(include_formulas=True)` leaves formula strings in
the producer's `values` array. The views do not normalize or discard fields.

Workbook discovery, current selection, UI control, and workbook mutations
remain explicit tools, not client methods. Executor registration determines
which read operations are callable; installing this distribution does not
grant access to a workbook or expose an operation.

The relay factory export is lazy; `create_relay_app` remains the factory
owned by `relay_app`.
