Basis MCP server

Add a new sheet to a session's workbook. The new sheet becomes the active sheet. Only works on sessions created from blank documents (not imported xlsx files).

Run a structural audit on the session's workbook. Returns formula errors, broken references, circular dependencies, hardcoded plugs, and verification mismatches.

Close a computation session and release its resources.

Create a named checkpoint of the session's current state. Returns the commit ID which can be passed to restore_session to roll back. Checkpoints live in the session only; to keep one in the Library's version history, call save_to_library after it (the version takes this message as its name).

Create a persistent computation session for a workbook. Pass library_file_id to load from the Library, base64 for raw xlsx bytes, url to fetch from a URL, or omit all for a blank model. Returns a session_id for subsequent calls. The workbook is recalculated on load, including formulas written by other tools that carry no cached values, so open a file you have edited to read back what its formulas compute (get_outputs, get_formula_range), or change inputs with set_inputs.

Create or retarget a named variable in the session's workbook. The name can then be used in set_inputs and get_outputs instead of cell references.

Evaluate an Excel formula locally and return the computed result: a quick way to check what a formula returns on a few sample values before you put it in a workbook. Pass data as a map of cell references to values (e.g. {"A1": 100, "A2": 200, "B1": "hello"}) and a formula string (e.g. "SUM(A1:A2)"). The formula is placed in row 1 of the first column right of your data, so don't reference that cell. A formula that evaluates to an Excel error returns type "error" with the code (#VALUE!, #N/A…) as a normal result; a formula that can't be parsed or uses an unsupported function is a tool error. Supports 278 Excel functions: math, financial (NPV, IRR, XIRR, PMT…), statistical, lookup, date/time, text, logical, and dynamic arrays (FILTER, SORT, UNIQUE, SEQUENCE…). Array expressions evaluate element by element inside SUMPRODUCT, LOOKUP, AGGREGATE, SMALL/LARGE, MATCH and INDEX. To check formulas that already live in a workbook, use create_session instead.

Parse an .xlsx workbook and return the full semantic NDJSON output (workbook_meta, sheet, cell, edge, image, image_summary, audit records).

Recalculate an .xlsx file and return it with the computed values saved in every formula cell. Use this after you create or edit a workbook with openpyxl or any other library that writes formulas without results: those files have no cached values, so pandas, openpyxl (data_only=True) and other readers see empty cells until the file is recalculated. Replaces running LibreOffice recalc.py. Returns file_base64 plus a summary of formula errors (#REF!, #DIV/0!, #NAME?, #VALUE!... with sheet and cell) and of formulas Basis could not compute: fix those and call again. Styles, charts, images, data validation, defined names, comments and VBA are carried over unchanged. Pass exactly one of url or base64.

Rename a sheet in a session's workbook. Formulas, named ranges and validations that reference the sheet are rewritten to the new name, so results don't change. Excel's rules apply: 1-31 characters, none of : \ / ? * [ ], no leading or trailing apostrophe, unique ignoring case.

Roll back a session to a previous commit. Reverts all cell changes made since that commit. Returns the number of cells that were changed by the rollback.

Save the session's workbook to the user's Library for durable storage. If the session was loaded from the Library or was previously saved, this creates a new version of that file. Otherwise it creates a new Library file. Returns the library_file_id. Each save is a named version in the Library's history: pass `message`, or it takes the latest commit_session message since the last save. commit_session checkpoints themselves stay in the session, so save after each step you want kept as a version.

Turn iterative calculation on or off for a session and recalculate. Needed for circular models (e.g. development pro formas where loan size depends on cost, which includes the loan's interest and fees): with it on, set_inputs re-converges the loop on every call. Saved with the session's next commit (restore_session to an earlier commit rolls it back) and written to the workbook, so an exported xlsx iterates in Excel too.

Set one or more cells in a session and recalculate. Keys can be defined names (e.g. "Revenue") or cell references (e.g. "Sheet1!A1"). A string starting with "=" is stored as a formula, so you can also try a formula in place and read the result with get_outputs. Returns the applied changes and which named outputs changed (effects).

Submit an .xlsx workbook for async parsing and get back a job handle (job_id, status_url, stream_url) without waiting for it to finish.

Trace the dependency graph from a cell. direction="precedents" shows what feeds into this cell; direction="dependents" shows what this cell feeds. Returns a BFS traversal up to the given depth with formula text and computed value at each node.

Compare two .xlsx workbooks and return the cell-level differences as JSON. Cells are joined on (sheet title, cell ref) and classified into added, removed, and changed (value and/or formula), with format-only changes bucketed separately. Provide exactly one of before_url/before_base64 and one of after_url/after_base64.

Get a session's workbook back as an .xlsx file with every formula's computed value saved in it. Recalculates first. Call this when you need the file itself: to give it to the user, or to read it with pandas, openpyxl (data_only=True) or any tool that is not Excel. Returns file_base64 and a summary of formula errors (#REF!, #DIV/0!, #NAME? with sheet and cell) and of anything that did not survive the save. Everything Basis does not model (styles, charts, images, data validation, defined names, comments, VBA) is carried over from the original file unchanged.

Return the formula text and computed value for a single cell. If the cell has no formula (constant or empty), formula will be null.

Batch-read formulas and computed values for a rectangular range of cells: the way to check what the formulas in a file compute. Returns {cell, formula, value, value_type} per cell; a formula that errors has value_type "error". Much more efficient than calling get_cell_formula repeatedly.

Check the status of a parse job submitted via submit_job.

Read computed values from a session, e.g. to check what the formulas in a workbook return. Pass defined names, cell refs ("B4", "Sheet1!B4") or ranges ("Sheet1!H2:H18", one entry per cell), or omit to read all defined names. A cell that evaluates to an Excel error is returned with type "error", not as a tool failure.

Inspect a session's model structure: sheets, defined names, cell/formula counts, and optionally the full dependency edge graph.

List all active computation sessions for the current user.

Export the session's current state as xlsx bytes (base64). Optionally creates a commit first. To get the file for a user or a non-Excel reader, with formula errors listed, prefer export_workbook.

Fetch the NDJSON output of a completed parse job. Pass `since` to resume from a record index.