openbooks-mcp 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,55 @@
1
+ # Python
2
+ __pycache__/
3
+ *.py[cod]
4
+ *.egg-info/
5
+ .pytest_cache/
6
+ .ruff_cache/
7
+ .mypy_cache/
8
+ .venv/
9
+ venv/
10
+ build/
11
+ dist/
12
+
13
+ # Secrets and local config
14
+ .env
15
+ .env.*
16
+ !.env.example
17
+ *.key
18
+ *.pem
19
+ .claude/
20
+
21
+ # Downloaded third-party datasets (licences: some are NC / share-alike; never redistribute)
22
+ data/raw/
23
+ data/download_log.json
24
+ data/*_stdout.txt
25
+
26
+ # Generated training data (rebuilt by scripts/train_roles.py)
27
+ data/*.pkl
28
+
29
+ # Internal-only weights: pretrained on CORD (CC BY-SA), must not be shipped
30
+ models/jepa_encoder.pt
31
+ # Experimental runs (leave-one-family-out etc.); only the promoted model in models/ is tracked
32
+ models/fam_*/
33
+ models/*_bak*/
34
+
35
+ # Web app (web/)
36
+ node_modules/
37
+ .next/
38
+ out/
39
+ *.tsbuildinfo
40
+ next-env.d.ts
41
+
42
+ # OS / editor
43
+ .DS_Store
44
+ Thumbs.db
45
+ .vscode/
46
+ .idea/
47
+ *.log
48
+
49
+ .hypothesis/
50
+
51
+ # Local deployment and tooling state
52
+ .netlify/
53
+ .neon/
54
+ .impeccable/
55
+ deploy/.rollout-state
@@ -0,0 +1,5 @@
1
+ Copyright Lumeo. All rights reserved.
2
+
3
+ You may install and use this package to connect MCP-compatible clients to
4
+ Open Books. Lumeo retains all other rights in this package. The dependencies
5
+ distributed separately from this package retain their respective licenses.
@@ -0,0 +1,30 @@
1
+ Metadata-Version: 2.5
2
+ Name: openbooks-mcp
3
+ Version: 0.1.0
4
+ Summary: Connect MCP-compatible agents to the Open Books financial document verification engine.
5
+ Project-URL: Documentation, https://openbooks.lumeo.co.in/docs/mcp
6
+ License-Expression: LicenseRef-Lumeo
7
+ License-File: LICENSE
8
+ Requires-Python: >=3.11
9
+ Requires-Dist: mcp<3,>=2.2
10
+ Requires-Dist: openbooks<0.3,>=0.2
11
+ Requires-Dist: pydantic<3,>=2.12
12
+ Requires-Dist: uvicorn<1,>=0.30
13
+ Provides-Extra: scan
14
+ Requires-Dist: openbooks[scan]<0.3,>=0.2; extra == 'scan'
15
+ Description-Content-Type: text/markdown
16
+
17
+ # Open Books MCP
18
+
19
+ Verify financial documents and inspect their released data, evidence and
20
+ assertions from an MCP-compatible agent. The server exposes two tool
21
+ definitions, `search` and `execute`. An execution can process a document and
22
+ inspect only the needed parts in the same ordered batch.
23
+
24
+ Install the wheel using Python 3.11 or newer. Point the MCP client at
25
+ `python -m openbooks_mcp --root /path/to/financial/files` using the interpreter
26
+ where the wheel is installed. Omit `--root` for synthetic samples and small
27
+ in-memory uploads.
28
+
29
+ See the [Open Books MCP guide](https://openbooks.lumeo.co.in/docs/mcp) for
30
+ downloads, agent configuration, batch examples and private HTTP setup.
@@ -0,0 +1,14 @@
1
+ # Open Books MCP
2
+
3
+ Verify financial documents and inspect their released data, evidence and
4
+ assertions from an MCP-compatible agent. The server exposes two tool
5
+ definitions, `search` and `execute`. An execution can process a document and
6
+ inspect only the needed parts in the same ordered batch.
7
+
8
+ Install the wheel using Python 3.11 or newer. Point the MCP client at
9
+ `python -m openbooks_mcp --root /path/to/financial/files` using the interpreter
10
+ where the wheel is installed. Omit `--root` for synthetic samples and small
11
+ in-memory uploads.
12
+
13
+ See the [Open Books MCP guide](https://openbooks.lumeo.co.in/docs/mcp) for
14
+ downloads, agent configuration, batch examples and private HTTP setup.
@@ -0,0 +1,30 @@
1
+ [build-system]
2
+ requires = ["hatchling>=1.27"]
3
+ build-backend = "hatchling.build"
4
+
5
+ [project]
6
+ name = "openbooks-mcp"
7
+ version = "0.1.0"
8
+ description = "Connect MCP-compatible agents to the Open Books financial document verification engine."
9
+ readme = "README.md"
10
+ requires-python = ">=3.11"
11
+ license = "LicenseRef-Lumeo"
12
+ license-files = ["LICENSE"]
13
+ dependencies = [
14
+ "mcp>=2.2,<3",
15
+ "openbooks>=0.2,<0.3",
16
+ "pydantic>=2.12,<3",
17
+ "uvicorn>=0.30,<1",
18
+ ]
19
+
20
+ [project.optional-dependencies]
21
+ scan = ["openbooks[scan]>=0.2,<0.3"]
22
+
23
+ [project.urls]
24
+ Documentation = "https://openbooks.lumeo.co.in/docs/mcp"
25
+
26
+ [project.scripts]
27
+ openbooks-mcp = "openbooks_mcp.__main__:main"
28
+
29
+ [tool.hatch.build.targets.wheel]
30
+ packages = ["src/openbooks_mcp"]
@@ -0,0 +1,3 @@
1
+ from importlib.metadata import version
2
+
3
+ __version__ = version("openbooks-mcp")
@@ -0,0 +1,52 @@
1
+ from __future__ import annotations
2
+
3
+ import argparse
4
+ import os
5
+ from pathlib import Path
6
+
7
+ import uvicorn
8
+
9
+ from . import __version__
10
+ from .server import build_server, private_http_app
11
+
12
+
13
+ def main() -> None:
14
+ parser = argparse.ArgumentParser(prog="openbooks-mcp")
15
+ parser.add_argument("--version", action="version", version=__version__)
16
+ parser.add_argument("--root", type=Path, help="approve a local input directory for stdio")
17
+ parser.add_argument("--transport", choices=("stdio", "streamable-http"), default="stdio")
18
+ parser.add_argument("--port", type=int, default=8791, help="private loopback HTTP port")
19
+ args = parser.parse_args()
20
+
21
+ if args.transport == "stdio":
22
+ root = args.root
23
+ if root is not None:
24
+ try:
25
+ root = root.resolve(strict=True)
26
+ if not root.is_dir():
27
+ parser.error("--root must name an existing directory")
28
+ except (OSError, RuntimeError):
29
+ parser.error("--root must name an existing directory")
30
+ build_server(root).run("stdio")
31
+ return
32
+
33
+ if args.root is not None:
34
+ parser.error("--root is only available over stdio")
35
+ if not 1 <= args.port <= 65535:
36
+ parser.error("--port must be between 1 and 65535")
37
+ token = os.environ.get("OPENBOOKS_MCP_TOKEN", "")
38
+ if not token.isascii() or len(token) < 32 or any(ch.isspace() or not ch.isprintable() for ch in token):
39
+ parser.error("set OPENBOOKS_MCP_TOKEN to a random ASCII token of at least 32 characters")
40
+
41
+ uvicorn.run(
42
+ private_http_app(token.encode("ascii")),
43
+ host="127.0.0.1",
44
+ port=args.port,
45
+ access_log=False,
46
+ limit_concurrency=8,
47
+ proxy_headers=False,
48
+ )
49
+
50
+
51
+ if __name__ == "__main__":
52
+ main()
@@ -0,0 +1,256 @@
1
+ from __future__ import annotations
2
+
3
+ import base64
4
+ import binascii
5
+ import json
6
+ import re
7
+ from dataclasses import dataclass
8
+ from decimal import Decimal
9
+ from pathlib import Path
10
+ from tempfile import TemporaryDirectory
11
+ from threading import BoundedSemaphore
12
+ from typing import Annotated, Any, Callable, Literal
13
+
14
+ from openbooks import EngineFault, Params, process
15
+ from openbooks.core.cli import engine_info
16
+ from openbooks.core.guard import ALLOWED_EXT, MAX_BYTES
17
+ from pydantic import BaseModel, ConfigDict, Field, ValidationError
18
+
19
+ MAX_STEPS = 8
20
+ MAX_UPLOAD = 1024 * 1024
21
+ MAX_ENCODED_UPLOAD = ((MAX_UPLOAD + 2) // 3) * 4
22
+ MAX_RESPONSE = 48 * 1024
23
+ # Reserved per step for the envelope and ids, so a batch of MAX_STEPS still fits MAX_RESPONSE.
24
+ STEP_ENVELOPE_BYTES = 192
25
+ SAMPLE = (
26
+ b"Date,Description,Debit,Credit,Balance\n"
27
+ b"02/01/2026,Sample payment,100.00,,900.00\n"
28
+ b"03/01/2026,Sample deposit,,50.00,950.00\n"
29
+ )
30
+ StepId = Annotated[str, Field(pattern=r"^[A-Za-z][A-Za-z0-9_-]{0,31}$")]
31
+ Opening = Annotated[str, Field(max_length=32, pattern=r"^[+-]?[0-9]+(\.[0-9]+)?$")]
32
+ Document = dict[str, Any]
33
+ Documents = dict[str, Document]
34
+
35
+
36
+ def compact(value: Any) -> str:
37
+ return json.dumps(value, separators=(",", ":"), allow_nan=False)
38
+
39
+
40
+ def _error_item(step_id: str, code: str, message: str) -> Document:
41
+ return {"id": step_id, "error": {"code": code, "message": message}}
42
+
43
+
44
+ class Step(BaseModel):
45
+ model_config = ConfigDict(extra="forbid", strict=True)
46
+
47
+ id: StepId
48
+ operation: Annotated[str, Field(max_length=40)]
49
+ arguments: dict[str, Any] = Field(default_factory=dict)
50
+
51
+
52
+ class Arguments(BaseModel):
53
+ model_config = ConfigDict(extra="forbid", strict=True)
54
+
55
+
56
+ class ProcessingOptions(Arguments):
57
+ currency: Annotated[str, Field(pattern=r"^[A-Z]{3}$")] | None = None
58
+ opening: Opening | None = None
59
+ date_order: Literal["dmy", "mdy"] | None = None
60
+ account: Annotated[str, Field(max_length=128)] | None = None
61
+ allow_derived_opening: bool = False
62
+ ocr: bool = True
63
+ model: bool = False
64
+
65
+ def params(self) -> Params:
66
+ values = self.model_dump(include=set(ProcessingOptions.model_fields))
67
+ if self.opening is not None:
68
+ values["opening"] = Decimal(self.opening)
69
+ return Params(**values)
70
+
71
+
72
+ class SampleInput(Arguments):
73
+ opening: Opening | None = None
74
+
75
+
76
+ class FileInput(ProcessingOptions):
77
+ path: Annotated[str, Field(min_length=1, max_length=512)]
78
+
79
+
80
+ class UploadInput(ProcessingOptions):
81
+ filename: Annotated[str, Field(pattern=r"^[a-zA-Z0-9][a-zA-Z0-9._ -]{0,127}$")]
82
+ content_base64: Annotated[str, Field(min_length=4, max_length=MAX_ENCODED_UPLOAD)]
83
+
84
+
85
+ class DocumentInput(Arguments):
86
+ from_step: StepId
87
+
88
+
89
+ class RecordsInput(DocumentInput):
90
+ collection: Literal["accounts", "parties", "batches", "transactions", "claims", "assertions", "evidence"]
91
+ offset: Annotated[int, Field(ge=0, le=1_000_000)] = 0
92
+ limit: Annotated[int, Field(ge=1, le=10)] = 5
93
+ prefix: Annotated[str, Field(max_length=80)] = ""
94
+
95
+
96
+ class OperationError(Exception):
97
+ def __init__(self, code: str, message: str) -> None:
98
+ self.code = code
99
+ super().__init__(message)
100
+
101
+
102
+ @dataclass(frozen=True)
103
+ class Operation:
104
+ description: str
105
+ arguments: type[Arguments]
106
+ run: Callable[[Any, Documents, str], Document]
107
+
108
+
109
+ class Operations:
110
+ def __init__(self, root: Path | None = None) -> None:
111
+ self.root = root
112
+ self._slots = BoundedSemaphore(2)
113
+ self._operations = {
114
+ "formats": Operation("List installed layouts and file limits for CSV, PDF, scans and financial exports.", Arguments, self._formats),
115
+ "process_sample": Operation("Verify a synthetic bank statement CSV. Supply opening 1000.00 for a release.", SampleInput, self._process_sample),
116
+ "process_upload": Operation("Verify a file sent as base64 bytes, up to 1 MiB.", UploadInput, self._process_upload),
117
+ "records": Operation("Read a bounded page of transactions, batches, accounts, claims, assertions or evidence from an earlier step.", RecordsInput, self._records),
118
+ "document": Operation("Return the complete released or refused JSON from an earlier step, subject to the response limit.", DocumentInput, self._document),
119
+ }
120
+ if self.root is not None:
121
+ self._operations["process_file"] = Operation(
122
+ "Verify a file at a relative path inside the user-approved local folder.", FileInput, self._process_file,
123
+ )
124
+
125
+ def search(self, query: str, details: bool) -> str:
126
+ terms = set(re.findall(r"[a-z0-9]+", query.lower()))
127
+ matches = []
128
+ for name, operation in self._operations.items():
129
+ keywords = set(re.findall(r"[a-z0-9]+", f"{name} {operation.description}".lower()))
130
+ score = len(terms & keywords)
131
+ if terms and not score:
132
+ continue
133
+ item = {"name": name, "description": operation.description}
134
+ if details:
135
+ item["arguments"] = operation.arguments.model_json_schema()
136
+ matches.append((score, item))
137
+ matches.sort(key=lambda entry: -entry[0])
138
+ return compact({"operations": [entry[1] for entry in matches], "max_steps": MAX_STEPS})
139
+
140
+ def execute(self, steps: list[Step]) -> str:
141
+ if len({step.id for step in steps}) != len(steps):
142
+ return compact({"error": {"code": "DUPLICATE_STEP", "message": "Step ids must be unique."}})
143
+ if not self._slots.acquire(blocking=False):
144
+ return compact({"error": {"code": "BUSY", "message": "Retry after outstanding runs finish."}})
145
+
146
+ documents: Documents = {}
147
+ results = []
148
+ try:
149
+ budget = MAX_RESPONSE - MAX_STEPS * STEP_ENVELOPE_BYTES
150
+ for step in steps:
151
+ item = self._run_step(step, documents)
152
+ if len(compact(results + [item])) > budget:
153
+ item = _error_item(step.id, "RESPONSE_LIMIT", "Request fewer records or a smaller page.")
154
+ results.append(item)
155
+ return compact({"steps": results})
156
+ finally:
157
+ self._slots.release()
158
+
159
+ def _run_step(self, step: Step, documents: Documents) -> Document:
160
+ try:
161
+ operation = self._operations.get(step.operation)
162
+ if operation is None:
163
+ raise OperationError("UNKNOWN_OPERATION", "Use search to find available operations.")
164
+ parameters = operation.arguments.model_validate(step.arguments)
165
+ return {"id": step.id, "result": operation.run(parameters, documents, step.id)}
166
+ except ValidationError:
167
+ return _error_item(step.id, "INVALID_ARGUMENTS", "Check the operation's argument schema with search.")
168
+ except OperationError as exc:
169
+ return _error_item(step.id, exc.code, str(exc))
170
+ except (EngineFault, OSError):
171
+ return _error_item(step.id, "ENGINE_ERROR", "The engine could not complete this operation. Check the install and input.")
172
+
173
+ @staticmethod
174
+ def _formats(_args: Arguments, _documents: Documents, _step: str) -> Document:
175
+ return {
176
+ **engine_info(),
177
+ "extensions": sorted(ALLOWED_EXT),
178
+ "max_file_bytes": MAX_BYTES,
179
+ "max_upload_bytes": MAX_UPLOAD,
180
+ }
181
+
182
+ def _process_sample(self, args: SampleInput, documents: Documents, step: str) -> Document:
183
+ options = Params(currency="INR", date_order="dmy", opening=Decimal(args.opening) if args.opening else None)
184
+ return self._process_bytes(SAMPLE, "statement.csv", options, documents, step)
185
+
186
+ def _process_file(self, args: FileInput, documents: Documents, step: str) -> Document:
187
+ path = Path(args.path)
188
+ if self.root is None or path.anchor or ".." in path.parts or "\0" in args.path:
189
+ raise OperationError("INVALID_PATH", "Use a relative path within the approved folder.")
190
+ try:
191
+ resolved = (self.root / path).resolve(strict=True)
192
+ if not resolved.is_relative_to(self.root) or not resolved.is_file():
193
+ raise OperationError("INVALID_PATH", "Use a regular file within the approved folder.")
194
+ except (OSError, RuntimeError):
195
+ raise OperationError("INVALID_PATH", "The file path could not be resolved.") from None
196
+ if resolved.stat().st_size > MAX_BYTES:
197
+ raise OperationError("INPUT_LIMIT", "The local file exceeds the engine limit.")
198
+ return self._process(resolved, args.params(), documents, step)
199
+
200
+ def _process_upload(self, args: UploadInput, documents: Documents, step: str) -> Document:
201
+ try:
202
+ payload = base64.b64decode(args.content_base64, validate=True)
203
+ except (ValueError, binascii.Error):
204
+ raise OperationError("INVALID_ENCODING", "Supply standard base64 without a data URL prefix.") from None
205
+ if len(payload) > MAX_UPLOAD:
206
+ raise OperationError("INPUT_LIMIT", "The decoded file exceeds 1 MiB.")
207
+ if Path(args.filename).suffix.lower() not in ALLOWED_EXT:
208
+ raise OperationError("UNSUPPORTED_INPUT", "Use an extension listed by the formats operation.")
209
+ return self._process_bytes(payload, args.filename, args.params(), documents, step)
210
+
211
+ def _process_bytes(self, payload: bytes, filename: str, params: Params, documents: Documents, step: str) -> Document:
212
+ with TemporaryDirectory(prefix="openbooks-mcp-") as directory:
213
+ path = Path(directory) / filename
214
+ path.write_bytes(payload)
215
+ return self._process(path, params, documents, step)
216
+
217
+ @staticmethod
218
+ def _process(path: Path, params: Params, documents: Documents, step: str) -> Document:
219
+ document = process(path, params, strict=True)
220
+ documents[step] = document
221
+ summary = {"schema_version": document["schema_version"], "status": document["status"]}
222
+ if document["status"] == "refused":
223
+ error = document["error"]
224
+ return {**summary, "error": {**error, "message": error["message"][:500]}}
225
+ return {
226
+ **summary,
227
+ "file": document["file"],
228
+ "counts": {name: len(items) for name, items in document["data"].items()},
229
+ "assertions": len(document["assertions"]),
230
+ }
231
+
232
+ @staticmethod
233
+ def _document(args: DocumentInput, documents: Documents, _step: str) -> Document:
234
+ if args.from_step not in documents:
235
+ raise OperationError("MISSING_DOCUMENT", "Reference an earlier processing step in this batch.")
236
+ return documents[args.from_step]
237
+
238
+ def _records(self, args: RecordsInput, documents: Documents, step: str) -> Document:
239
+ document = self._document(args, documents, step)
240
+ if document["status"] != "ok":
241
+ raise OperationError("DOCUMENT_REFUSED", "Inspect the refusal before requesting records.")
242
+ if args.collection == "evidence":
243
+ records = [
244
+ {"key": key, **value} for key, value in document["evidence"].items()
245
+ if key.startswith(args.prefix)
246
+ ]
247
+ else:
248
+ source = document["assertions"] if args.collection == "assertions" else document["data"][args.collection]
249
+ records = [record for record in source if str(record.get("id", "")).startswith(args.prefix)]
250
+ end = args.offset + args.limit
251
+ return {
252
+ "collection": args.collection,
253
+ "items": records[args.offset:end],
254
+ "total": len(records),
255
+ "next_offset": end if end < len(records) else None,
256
+ }
@@ -0,0 +1,65 @@
1
+ from __future__ import annotations
2
+
3
+ import asyncio
4
+ from pathlib import Path
5
+ from secrets import compare_digest
6
+ from typing import Annotated
7
+
8
+ from mcp.server.mcpserver import MCPServer
9
+ from mcp.types import ToolAnnotations
10
+ from pydantic import Field
11
+
12
+ from . import __version__
13
+ from .operations import MAX_STEPS, Operations, Step
14
+
15
+ MAX_HTTP_BODY = 2 * 1024 * 1024
16
+ READ_ONLY = ToolAnnotations(read_only_hint=True, destructive_hint=False, open_world_hint=False)
17
+ DOCS = "https://openbooks.lumeo.co.in/docs/mcp"
18
+
19
+
20
+ def build_server(root: Path | None = None) -> MCPServer:
21
+ operations = Operations(root)
22
+ server = MCPServer(
23
+ "openbooks",
24
+ title="Open Books",
25
+ version=__version__,
26
+ website_url=DOCS,
27
+ instructions="Use search to discover operations. Use execute to verify documents and inspect their proof in one ordered batch.",
28
+ log_level="WARNING",
29
+ )
30
+
31
+ @server.tool(annotations=READ_ONLY, structured_output=False)
32
+ def search(query: Annotated[str, Field(max_length=160)] = "", details: bool = False) -> str:
33
+ """Find Open Books operations by name or keyword. Request details to see argument schemas."""
34
+ return operations.search(query, details)
35
+
36
+ @server.tool(annotations=READ_ONLY, structured_output=False)
37
+ async def execute(steps: Annotated[list[Step], Field(min_length=1, max_length=MAX_STEPS)]) -> str:
38
+ """Run an ordered batch. Each step has an id, operation and arguments. Use from_step to inspect a preceding document."""
39
+ return await asyncio.to_thread(operations.execute, steps)
40
+
41
+ return server
42
+
43
+
44
+ def private_http_app(token: bytes):
45
+ app = build_server().streamable_http_app(
46
+ stateless_http=True,
47
+ json_response=True,
48
+ max_request_body_size=MAX_HTTP_BODY,
49
+ )
50
+ authorization = b"Bearer " + token
51
+
52
+ async def protected(scope, receive, send):
53
+ if scope["type"] == "http":
54
+ provided = [value for name, value in scope["headers"] if name == b"authorization"]
55
+ if len(provided) != 1 or not compare_digest(authorization, provided[0]):
56
+ await send({
57
+ "type": "http.response.start",
58
+ "status": 401,
59
+ "headers": [(b"www-authenticate", b"Bearer"), (b"cache-control", b"no-store")],
60
+ })
61
+ await send({"type": "http.response.body", "body": b"Authorization required"})
62
+ return
63
+ await app(scope, receive, send)
64
+
65
+ return protected
@@ -0,0 +1,250 @@
1
+ from __future__ import annotations
2
+
3
+ import asyncio
4
+ import base64
5
+ import json
6
+ import os
7
+ import subprocess
8
+ import sys
9
+ from pathlib import Path
10
+
11
+ import pytest
12
+ from mcp import ClientSession, StdioServerParameters
13
+ from mcp.client.stdio import stdio_client
14
+
15
+ from openbooks_mcp.operations import MAX_RESPONSE, MAX_UPLOAD, SAMPLE, Operations, Step
16
+ from openbooks_mcp.server import private_http_app
17
+
18
+
19
+ def step(id: str, operation: str, **arguments) -> Step:
20
+ return Step(id=id, operation=operation, arguments=arguments)
21
+
22
+
23
+ def test_local_scope_and_document_projections(tmp_path: Path) -> None:
24
+ root = tmp_path / "allowed"
25
+ root.mkdir()
26
+ (root / "statement.csv").write_bytes(SAMPLE)
27
+ outside = tmp_path / "other.csv"
28
+ outside.write_bytes(SAMPLE)
29
+ ops = Operations(root.resolve())
30
+
31
+ response = json.loads(ops.execute([
32
+ step("escape", "process_file", path="../other.csv"),
33
+ step("absolute", "process_file", path=str(outside.resolve())),
34
+ step("verify", "process_file", path="statement.csv", currency="INR", opening="1000.00", date_order="dmy"),
35
+ step("rows", "records", from_step="verify", collection="transactions", limit=1),
36
+ step("proof", "records", from_step="verify", collection="evidence", prefix="txn-00001."),
37
+ ]))
38
+ denied, absolute, verified, rows, proof = response["steps"]
39
+ assert denied["error"]["code"] == absolute["error"]["code"] == "INVALID_PATH"
40
+ assert verified["result"]["status"] == "ok"
41
+ assert verified["result"]["counts"]["transactions"] == 2
42
+ assert rows["result"]["items"][0]["amount"] == {"amount": "100.00", "currency": "INR"}
43
+ assert rows["result"]["next_offset"] == 1
44
+ assert all(row["key"].startswith("txn-00001.") for row in proof["result"]["items"])
45
+
46
+
47
+ def test_symlink_cannot_escape_local_scope(tmp_path: Path) -> None:
48
+ root = tmp_path / "allowed"
49
+ root.mkdir()
50
+ outside = tmp_path / "other.csv"
51
+ outside.write_bytes(SAMPLE)
52
+ try:
53
+ (root / "linked.csv").symlink_to(outside)
54
+ except OSError:
55
+ pytest.skip("this environment cannot create symlinks")
56
+ response = json.loads(Operations(root.resolve()).execute([step("link", "process_file", path="linked.csv")]))
57
+ assert response["steps"][0]["error"]["code"] == "INVALID_PATH"
58
+
59
+
60
+ def test_refusals_and_scoped_uploads() -> None:
61
+ ops = Operations()
62
+ discovered = json.loads(ops.search("process", True))
63
+ assert "process_file" not in [operation["name"] for operation in discovered["operations"]]
64
+ encoded = base64.b64encode(SAMPLE).decode("ascii")
65
+ response = json.loads(ops.execute([
66
+ step("refuse", "process_sample"),
67
+ step("denied", "records", from_step="refuse", collection="transactions"),
68
+ step("missing", "document", from_step="unknown"),
69
+ step("invalid", "process_upload", filename="../escape.csv", content_base64=encoded),
70
+ step("bad_b64", "process_upload", filename="statement.csv", content_base64="!!!!"),
71
+ step("upload", "process_upload", filename="statement.csv", content_base64=encoded, currency="INR", opening="1000.00"),
72
+ step("closing", "records", from_step="upload", collection="batches"),
73
+ ]))
74
+ refused, denied, missing, invalid, bad_b64, upload, closing = response["steps"]
75
+ assert refused["result"]["error"]["code"] == "PARSE_ERROR"
76
+ assert denied["error"]["code"] == "DOCUMENT_REFUSED"
77
+ assert missing["error"]["code"] == "MISSING_DOCUMENT"
78
+ assert invalid["error"]["code"] == "INVALID_ARGUMENTS"
79
+ assert bad_b64["error"]["code"] == "INVALID_ENCODING"
80
+ assert upload["result"]["status"] == "ok"
81
+ assert closing["result"]["items"][0]["closing"]["amount"] == "950.00"
82
+
83
+
84
+ def test_batch_limit_preserves_independent_results() -> None:
85
+ ops = Operations()
86
+ rows = b"".join(
87
+ f"02/01/2026,Sample {number},,1.00,{1000 + number}.00\n".encode()
88
+ for number in range(1, 201)
89
+ )
90
+ encoded = base64.b64encode(SAMPLE.splitlines(keepends=True)[0] + rows).decode()
91
+ response = ops.execute([
92
+ step("upload", "process_upload", filename="rows.csv", content_base64=encoded, currency="INR", opening="1000.00"),
93
+ step("big", "document", from_step="upload"),
94
+ step("slice", "records", from_step="upload", collection="transactions", limit=1),
95
+ ])
96
+ assert len(response) <= MAX_RESPONSE
97
+ uploaded, big, sliced = json.loads(response)["steps"]
98
+ assert uploaded["result"]["status"] == "ok"
99
+ assert big["error"]["code"] == "RESPONSE_LIMIT"
100
+ assert sliced["result"]["total"] == 200
101
+ duplicates = json.loads(ops.execute([step("same", "formats"), step("same", "formats")]))
102
+ assert duplicates["error"]["code"] == "DUPLICATE_STEP"
103
+
104
+
105
+ def test_stdio_lists_two_tools_and_executes_a_batch() -> None:
106
+ async def run() -> None:
107
+ args = StdioServerParameters(command=sys.executable, args=["-m", "openbooks_mcp"])
108
+ async with stdio_client(args) as (read, write):
109
+ async with ClientSession(read, write) as session:
110
+ await session.initialize()
111
+ tools = (await session.list_tools()).tools
112
+ assert [tool.name for tool in tools] == ["search", "execute"]
113
+ result = await session.call_tool("execute", {"steps": [
114
+ {"id": "csv", "operation": "process_sample", "arguments": {"opening": "1000.00"}},
115
+ {"id": "proof", "operation": "records", "arguments": {"from_step": "csv", "collection": "assertions"}},
116
+ ]})
117
+ assert not result.is_error
118
+ assert result.structured_content is None
119
+ assert len(result.content) == 1 and result.content[0].type == "text"
120
+ parsed = json.loads(result.content[0].text)["steps"]
121
+ assert parsed[0]["result"]["status"] == "ok"
122
+ assert all(row["passed"] for row in parsed[1]["result"]["items"])
123
+
124
+ asyncio.run(run())
125
+
126
+
127
+ def run_one(ops: Operations, operation: str, **arguments) -> dict:
128
+ return json.loads(ops.execute([step("only", operation, **arguments)]))["steps"][0]
129
+
130
+
131
+ def test_search_matches_keywords_and_rejects_unknown_terms() -> None:
132
+ ops = Operations()
133
+ names = [op["name"] for op in json.loads(ops.search("upload", False))["operations"]]
134
+ assert names[0] == "process_upload"
135
+ assert json.loads(ops.search("zzzz-no-match", False))["operations"] == []
136
+ everything = json.loads(ops.search("", False))["operations"]
137
+ assert {op["name"] for op in everything} == {"formats", "process_sample", "process_upload", "records", "document"}
138
+ assert all("arguments" not in op for op in everything)
139
+
140
+
141
+ def test_unknown_operation_and_extra_arguments_are_refused() -> None:
142
+ ops = Operations()
143
+ assert run_one(ops, "no_such_op")["error"]["code"] == "UNKNOWN_OPERATION"
144
+ assert run_one(ops, "process_sample", unexpected=1)["error"]["code"] == "INVALID_ARGUMENTS"
145
+ assert run_one(ops, "process_sample", opening="1e3")["error"]["code"] == "INVALID_ARGUMENTS"
146
+ assert run_one(ops, "process_sample", opening="1000.00")["result"]["status"] == "ok"
147
+
148
+
149
+ def test_upload_rejects_oversized_data_urls_and_wrong_extensions() -> None:
150
+ ops = Operations()
151
+ oversized = base64.b64encode(b"x" * (MAX_UPLOAD + 1)).decode("ascii")
152
+ assert run_one(ops, "process_upload", filename="a.csv", content_base64=oversized)["error"]["code"] == "INPUT_LIMIT"
153
+ prefixed = "data:text/csv;base64," + base64.b64encode(SAMPLE).decode("ascii")
154
+ assert run_one(ops, "process_upload", filename="a.csv", content_base64=prefixed)["error"]["code"] == "INVALID_ENCODING"
155
+ encoded = base64.b64encode(SAMPLE).decode("ascii")
156
+ assert run_one(ops, "process_upload", filename="a.exe", content_base64=encoded)["error"]["code"] == "UNSUPPORTED_INPUT"
157
+
158
+
159
+ def test_upload_accepts_unicode_descriptions_and_empty_payload_is_refused_cleanly() -> None:
160
+ ops = Operations()
161
+ unicode_rows = "02/01/2026,Café ₹ 支払い,100.00,,900.00\n".encode()
162
+ encoded = base64.b64encode(SAMPLE.splitlines(keepends=True)[0] + unicode_rows).decode()
163
+ result = run_one(ops, "process_upload", filename="unicode.csv", content_base64=encoded, currency="INR", opening="1000.00")
164
+ assert result["result"]["status"] in {"ok", "refused"}
165
+ empty = run_one(ops, "process_upload", filename="empty.csv", content_base64="")
166
+ assert empty["error"]["code"] == "INVALID_ARGUMENTS"
167
+
168
+
169
+ def test_process_file_refuses_null_bytes_and_parent_segments(tmp_path: Path) -> None:
170
+ root = tmp_path / "allowed"
171
+ root.mkdir()
172
+ ops = Operations(root.resolve())
173
+ for path in ("sub/../../other.csv", "nul\x00.csv", "./missing.csv"):
174
+ error = run_one(ops, "process_file", path=path)
175
+ assert error["error"]["code"] == "INVALID_PATH", path
176
+ assert run_one(ops, "process_file", path="")["error"]["code"] == "INVALID_ARGUMENTS"
177
+
178
+
179
+ def test_process_file_refuses_directories(tmp_path: Path) -> None:
180
+ root = tmp_path / "allowed"
181
+ (root / "folder.csv").mkdir(parents=True)
182
+ ops = Operations(root.resolve())
183
+ assert run_one(ops, "process_file", path="folder.csv")["error"]["code"] == "INVALID_PATH"
184
+
185
+
186
+ def test_records_paging_handles_empty_and_out_of_range_offsets() -> None:
187
+ ops = Operations()
188
+ upload = step("verify", "process_sample", opening="1000.00")
189
+ beyond = json.loads(ops.execute([
190
+ upload,
191
+ step("page", "records", from_step="verify", collection="transactions", offset=999, limit=5),
192
+ step("prefix", "records", from_step="verify", collection="transactions", prefix="no-such-id"),
193
+ ]))["steps"]
194
+ assert beyond[1]["result"] == {"collection": "transactions", "items": [], "total": 2, "next_offset": None}
195
+ assert beyond[2]["result"]["total"] == 0
196
+
197
+
198
+ def test_records_refuses_unknown_collections_and_bad_limits() -> None:
199
+ ops = Operations()
200
+ assert run_one(ops, "records", from_step="x", collection="secrets")["error"]["code"] == "INVALID_ARGUMENTS"
201
+ assert run_one(ops, "records", from_step="x", collection="transactions", limit=0)["error"]["code"] == "INVALID_ARGUMENTS"
202
+ assert run_one(ops, "records", from_step="x", collection="transactions", limit=11)["error"]["code"] == "INVALID_ARGUMENTS"
203
+
204
+
205
+ def test_duplicate_step_ids_are_rejected_before_any_work() -> None:
206
+ ops = Operations()
207
+ response = json.loads(ops.execute([step("a", "formats"), step("a", "process_sample")]))
208
+ assert response["error"]["code"] == "DUPLICATE_STEP"
209
+ assert "steps" not in response
210
+
211
+
212
+ def run_cli(*args: str) -> subprocess.CompletedProcess[str]:
213
+ return subprocess.run(
214
+ [sys.executable, "-m", "openbooks_mcp", *args],
215
+ capture_output=True, text=True, timeout=60, env={**os.environ, "OPENBOOKS_MCP_TOKEN": ""},
216
+ )
217
+
218
+
219
+ def test_cli_rejects_root_for_http_and_missing_roots(tmp_path: Path) -> None:
220
+ http_with_root = run_cli("--transport", "streamable-http", "--root", str(tmp_path))
221
+ assert http_with_root.returncode == 2
222
+ assert "only available over stdio" in http_with_root.stderr
223
+ missing = run_cli("--root", str(tmp_path / "does-not-exist"))
224
+ assert missing.returncode == 2
225
+ assert "existing directory" in missing.stderr
226
+
227
+
228
+ def test_cli_rejects_weak_tokens_and_out_of_range_ports() -> None:
229
+ weak = run_cli("--transport", "streamable-http")
230
+ assert weak.returncode == 2 and "OPENBOOKS_MCP_TOKEN" in weak.stderr
231
+ bad_port = run_cli("--transport", "streamable-http", "--port", "70000")
232
+ assert bad_port.returncode == 2 and "--port" in bad_port.stderr
233
+
234
+
235
+ def test_http_requires_bearer_before_reading_body() -> None:
236
+ async def run() -> None:
237
+ app = private_http_app(b"test-token-with-at-least-32-characters")
238
+ sent = []
239
+
240
+ async def receive():
241
+ raise AssertionError("unauthenticated request body was read")
242
+
243
+ async def send(message):
244
+ sent.append(message)
245
+
246
+ await app({"type": "http", "headers": []}, receive, send)
247
+ assert sent[0]["status"] == 401
248
+ assert (b"www-authenticate", b"Bearer") in sent[0]["headers"]
249
+
250
+ asyncio.run(run())