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.
- openbooks_mcp-0.1.0/.gitignore +55 -0
- openbooks_mcp-0.1.0/LICENSE +5 -0
- openbooks_mcp-0.1.0/PKG-INFO +30 -0
- openbooks_mcp-0.1.0/README.md +14 -0
- openbooks_mcp-0.1.0/pyproject.toml +30 -0
- openbooks_mcp-0.1.0/src/openbooks_mcp/__init__.py +3 -0
- openbooks_mcp-0.1.0/src/openbooks_mcp/__main__.py +52 -0
- openbooks_mcp-0.1.0/src/openbooks_mcp/operations.py +256 -0
- openbooks_mcp-0.1.0/src/openbooks_mcp/server.py +65 -0
- openbooks_mcp-0.1.0/tests/test_mcp.py +250 -0
|
@@ -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,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,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())
|