simtest-funnel-mcp 1.0.0b12__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,14 @@
1
+ node_modules/
2
+ .env
3
+ .copilot
4
+ scratch/
5
+ .pnpm-store/
6
+ target/
7
+ target/doc/
8
+ __pycache__/
9
+ *.so
10
+ *.pyc
11
+ *.pyo
12
+ .pytest_cache/
13
+ dist/
14
+ output.txt
@@ -0,0 +1,153 @@
1
+ Metadata-Version: 2.5
2
+ Name: simtest-funnel-mcp
3
+ Version: 1.0.0-beta.12
4
+ Summary: Local MCP server for funnel (tolerance-tube) comparison of signals in CSV files
5
+ Project-URL: Repository, https://github.com/Symoptia/simtest-funnel
6
+ Author: Symoptia contributors
7
+ License: MIT
8
+ Requires-Python: >=3.12
9
+ Requires-Dist: mcp<3,>=2.3
10
+ Requires-Dist: numpy>=1.26
11
+ Requires-Dist: pandas>=2
12
+ Requires-Dist: simtest-funnel<2,>=1.0.0b11
13
+ Description-Content-Type: text/markdown
14
+
15
+ # simtest-funnel-mcp
16
+
17
+ A local [MCP](https://modelcontextprotocol.io) server that lets AI agents
18
+ (Claude Code, Claude Desktop, any MCP client) compare signals stored in
19
+ local CSV files with the funnel (tolerance-tube) algorithm of
20
+ [simtest-funnel](https://github.com/Symoptia/simtest-funnel), a port of
21
+ [LBNL Funnel](https://github.com/lbl-srg/funnel).
22
+
23
+ The server reads the files itself, so raw samples never enter the model's
24
+ context. It is read-only and stateless: every call names the files it
25
+ reads; nothing is written and no network connection is opened. Transport:
26
+ stdio.
27
+
28
+ > **Platform note:** `simtest-funnel` is currently published to PyPI only
29
+ > as a Linux x86-64 / CPython 3.12 wheel, so `uvx simtest-funnel-mcp`
30
+ > works only there until cross-platform wheels are published. From a
31
+ > checkout of this repository it works wherever the Rust extension builds.
32
+
33
+ ## Tools
34
+
35
+ ### `describe_signals(path)`
36
+
37
+ Time column (and how it was chosen), row count, time start/end/span,
38
+ sampling (uniform or not; min/median/max step), per-column min/max/range
39
+ and data problems (non-numeric or empty cells, time not non-decreasing).
40
+ Use it to choose columns and tolerances.
41
+
42
+ ### `compare_signals(reference_path, test_path, ...)`
43
+
44
+ | Argument | Default | Meaning |
45
+ | --- | --- | --- |
46
+ | `columns` | all common columns | Signal columns to compare |
47
+ | `tolerances` | one set, library default | List of sets: optional unique `label` plus any of the six coefficients |
48
+ | `column_tolerances` | none | `{column: coefficients}` overrides, applied per axis |
49
+ | `x_range` | unbounded | `{"lo": .., "hi": ..}` time window |
50
+ | `max_intervals` | 5 | Violation intervals listed per failing row (largest deviation first) |
51
+ | `max_rows` | 100 | Rows returned (errors, then failures, then passes); totals always cover all rows |
52
+ | `include_snippet` | false | Add a pytest file reproducing the comparison (for CI) |
53
+
54
+ The result has one row per (column, tolerance set) with verdict
55
+ (`pass` / `fail` / `error`), the library status code, points outside the
56
+ tube, fractions of points and span outside, the worst deviation and, for
57
+ failures only, the violation intervals. Missing columns, bad data and
58
+ other per-column problems are reported in their rows instead of failing
59
+ the call. Both structured content and a short text rendering are returned.
60
+
61
+ ## CSV dialect
62
+
63
+ Comma-separated, one header row, lines starting with `#` ignored. The time
64
+ column is the first column named `time` (case-insensitive), otherwise the
65
+ first column; the choice is echoed back.
66
+
67
+ ## Tolerances
68
+
69
+ Six coefficients, x = time axis, y = signal value. At each reference sample
70
+ the tube half-widths are
71
+
72
+ ```text
73
+ half_x = max(atolx, rtolx * time_span_ref, ltolx * |t|)
74
+ half_y = max(atoly, rtoly * value_range_ref, ltoly * |y_ref|)
75
+ ```
76
+
77
+ - `atol*`: absolute (time units / signal units)
78
+ - `rtol*`: fraction of the reference time span / value range
79
+ - `ltol*`: fraction of the local `|t|` / `|y_ref|`
80
+
81
+ Omitted coefficients are resolved by the library, per axis: an axis with no
82
+ coefficient given gets `rtol = 0.002`; an axis with any coefficient given
83
+ uses `0` for its others; an explicit `0` counts as given. The six resolved
84
+ values are always echoed back.
85
+
86
+ **Tolerance in x** widens the tube along time, so a test signal shifted or
87
+ delayed by up to `half_x` still passes; steep edges and small timing
88
+ offsets then do not cause false failures.
89
+
90
+ "1 % in y, 0.5 s in x" is `{"rtoly": 0.01, "atolx": 0.5}` (or `ltoly` for
91
+ 1 % of the local value).
92
+
93
+ ## Registering the server
94
+
95
+ ### Claude Code
96
+
97
+ Once published to PyPI:
98
+
99
+ ```bash
100
+ claude mcp add simtest-funnel -- uvx simtest-funnel-mcp
101
+ ```
102
+
103
+ From a checkout of this repository (use `--scope user` to make it available
104
+ in every project):
105
+
106
+ ```bash
107
+ claude mcp add simtest-funnel -- uv run --directory /path/to/simtest-funnel --quiet simtest-funnel-mcp
108
+ ```
109
+
110
+ Inside this repository nothing needs to be registered: the checked-in
111
+ [`.mcp.json`](../../.mcp.json) starts the server with `uv run` from the
112
+ workspace (Claude Code asks for approval the first time).
113
+
114
+ ### Claude Desktop
115
+
116
+ Add to `claude_desktop_config.json` (Settings → Developer → Edit Config):
117
+
118
+ ```json
119
+ {
120
+ "mcpServers": {
121
+ "simtest-funnel": {
122
+ "command": "uvx",
123
+ "args": ["simtest-funnel-mcp"]
124
+ }
125
+ }
126
+ }
127
+ ```
128
+
129
+ or, from a checkout:
130
+
131
+ ```json
132
+ {
133
+ "mcpServers": {
134
+ "simtest-funnel": {
135
+ "command": "uv",
136
+ "args": ["run", "--directory", "/path/to/simtest-funnel", "--quiet", "simtest-funnel-mcp"]
137
+ }
138
+ }
139
+ }
140
+ ```
141
+
142
+ Use absolute paths in tool calls. When the client declares workspace roots,
143
+ the server refuses paths outside them and resolves relative paths against
144
+ the first root.
145
+
146
+ ## Development
147
+
148
+ ```bash
149
+ make build # builds the native simtest-funnel module
150
+ make test-python # includes python/simtest-funnel-mcp/tests (incl. stdio end-to-end)
151
+ make lint-python # mypy --strict
152
+ uv run simtest-funnel-mcp # start the server on stdio
153
+ ```
@@ -0,0 +1,139 @@
1
+ # simtest-funnel-mcp
2
+
3
+ A local [MCP](https://modelcontextprotocol.io) server that lets AI agents
4
+ (Claude Code, Claude Desktop, any MCP client) compare signals stored in
5
+ local CSV files with the funnel (tolerance-tube) algorithm of
6
+ [simtest-funnel](https://github.com/Symoptia/simtest-funnel), a port of
7
+ [LBNL Funnel](https://github.com/lbl-srg/funnel).
8
+
9
+ The server reads the files itself, so raw samples never enter the model's
10
+ context. It is read-only and stateless: every call names the files it
11
+ reads; nothing is written and no network connection is opened. Transport:
12
+ stdio.
13
+
14
+ > **Platform note:** `simtest-funnel` is currently published to PyPI only
15
+ > as a Linux x86-64 / CPython 3.12 wheel, so `uvx simtest-funnel-mcp`
16
+ > works only there until cross-platform wheels are published. From a
17
+ > checkout of this repository it works wherever the Rust extension builds.
18
+
19
+ ## Tools
20
+
21
+ ### `describe_signals(path)`
22
+
23
+ Time column (and how it was chosen), row count, time start/end/span,
24
+ sampling (uniform or not; min/median/max step), per-column min/max/range
25
+ and data problems (non-numeric or empty cells, time not non-decreasing).
26
+ Use it to choose columns and tolerances.
27
+
28
+ ### `compare_signals(reference_path, test_path, ...)`
29
+
30
+ | Argument | Default | Meaning |
31
+ | --- | --- | --- |
32
+ | `columns` | all common columns | Signal columns to compare |
33
+ | `tolerances` | one set, library default | List of sets: optional unique `label` plus any of the six coefficients |
34
+ | `column_tolerances` | none | `{column: coefficients}` overrides, applied per axis |
35
+ | `x_range` | unbounded | `{"lo": .., "hi": ..}` time window |
36
+ | `max_intervals` | 5 | Violation intervals listed per failing row (largest deviation first) |
37
+ | `max_rows` | 100 | Rows returned (errors, then failures, then passes); totals always cover all rows |
38
+ | `include_snippet` | false | Add a pytest file reproducing the comparison (for CI) |
39
+
40
+ The result has one row per (column, tolerance set) with verdict
41
+ (`pass` / `fail` / `error`), the library status code, points outside the
42
+ tube, fractions of points and span outside, the worst deviation and, for
43
+ failures only, the violation intervals. Missing columns, bad data and
44
+ other per-column problems are reported in their rows instead of failing
45
+ the call. Both structured content and a short text rendering are returned.
46
+
47
+ ## CSV dialect
48
+
49
+ Comma-separated, one header row, lines starting with `#` ignored. The time
50
+ column is the first column named `time` (case-insensitive), otherwise the
51
+ first column; the choice is echoed back.
52
+
53
+ ## Tolerances
54
+
55
+ Six coefficients, x = time axis, y = signal value. At each reference sample
56
+ the tube half-widths are
57
+
58
+ ```text
59
+ half_x = max(atolx, rtolx * time_span_ref, ltolx * |t|)
60
+ half_y = max(atoly, rtoly * value_range_ref, ltoly * |y_ref|)
61
+ ```
62
+
63
+ - `atol*`: absolute (time units / signal units)
64
+ - `rtol*`: fraction of the reference time span / value range
65
+ - `ltol*`: fraction of the local `|t|` / `|y_ref|`
66
+
67
+ Omitted coefficients are resolved by the library, per axis: an axis with no
68
+ coefficient given gets `rtol = 0.002`; an axis with any coefficient given
69
+ uses `0` for its others; an explicit `0` counts as given. The six resolved
70
+ values are always echoed back.
71
+
72
+ **Tolerance in x** widens the tube along time, so a test signal shifted or
73
+ delayed by up to `half_x` still passes; steep edges and small timing
74
+ offsets then do not cause false failures.
75
+
76
+ "1 % in y, 0.5 s in x" is `{"rtoly": 0.01, "atolx": 0.5}` (or `ltoly` for
77
+ 1 % of the local value).
78
+
79
+ ## Registering the server
80
+
81
+ ### Claude Code
82
+
83
+ Once published to PyPI:
84
+
85
+ ```bash
86
+ claude mcp add simtest-funnel -- uvx simtest-funnel-mcp
87
+ ```
88
+
89
+ From a checkout of this repository (use `--scope user` to make it available
90
+ in every project):
91
+
92
+ ```bash
93
+ claude mcp add simtest-funnel -- uv run --directory /path/to/simtest-funnel --quiet simtest-funnel-mcp
94
+ ```
95
+
96
+ Inside this repository nothing needs to be registered: the checked-in
97
+ [`.mcp.json`](../../.mcp.json) starts the server with `uv run` from the
98
+ workspace (Claude Code asks for approval the first time).
99
+
100
+ ### Claude Desktop
101
+
102
+ Add to `claude_desktop_config.json` (Settings → Developer → Edit Config):
103
+
104
+ ```json
105
+ {
106
+ "mcpServers": {
107
+ "simtest-funnel": {
108
+ "command": "uvx",
109
+ "args": ["simtest-funnel-mcp"]
110
+ }
111
+ }
112
+ }
113
+ ```
114
+
115
+ or, from a checkout:
116
+
117
+ ```json
118
+ {
119
+ "mcpServers": {
120
+ "simtest-funnel": {
121
+ "command": "uv",
122
+ "args": ["run", "--directory", "/path/to/simtest-funnel", "--quiet", "simtest-funnel-mcp"]
123
+ }
124
+ }
125
+ }
126
+ ```
127
+
128
+ Use absolute paths in tool calls. When the client declares workspace roots,
129
+ the server refuses paths outside them and resolves relative paths against
130
+ the first root.
131
+
132
+ ## Development
133
+
134
+ ```bash
135
+ make build # builds the native simtest-funnel module
136
+ make test-python # includes python/simtest-funnel-mcp/tests (incl. stdio end-to-end)
137
+ make lint-python # mypy --strict
138
+ uv run simtest-funnel-mcp # start the server on stdio
139
+ ```
@@ -0,0 +1,27 @@
1
+ [build-system]
2
+ requires = ["hatchling>=1.26"]
3
+ build-backend = "hatchling.build"
4
+
5
+ [project]
6
+ name = "simtest-funnel-mcp"
7
+ version = "1.0.0-beta.12"
8
+ description = "Local MCP server for funnel (tolerance-tube) comparison of signals in CSV files"
9
+ readme = "README.md"
10
+ requires-python = ">=3.12"
11
+ license = { text = "MIT" }
12
+ authors = [{ name = "Symoptia contributors" }]
13
+ dependencies = [
14
+ "mcp>=2.3,<3",
15
+ "simtest-funnel>=1.0.0b11,<2",
16
+ "numpy>=1.26",
17
+ "pandas>=2",
18
+ ]
19
+
20
+ [project.scripts]
21
+ simtest-funnel-mcp = "simtest_funnel_mcp.server:main"
22
+
23
+ [project.urls]
24
+ Repository = "https://github.com/Symoptia/simtest-funnel"
25
+
26
+ [tool.hatch.build.targets.wheel]
27
+ packages = ["src/simtest_funnel_mcp"]
@@ -0,0 +1,18 @@
1
+ """Local MCP server for funnel (tolerance-tube) comparison of CSV signals.
2
+
3
+ The server is a thin adapter over :mod:`simtest.funnel`: it reads local CSV
4
+ files, calls the library and returns compact, bounded results. Start it with
5
+ the ``simtest-funnel-mcp`` console script (stdio transport).
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ from importlib.metadata import PackageNotFoundError
11
+ from importlib.metadata import version as _dist_version
12
+
13
+ try:
14
+ __version__ = _dist_version("simtest-funnel-mcp")
15
+ except PackageNotFoundError: # pragma: no cover - running from a source tree
16
+ __version__ = "0.0.0"
17
+
18
+ __all__ = ["__version__"]
@@ -0,0 +1,6 @@
1
+ """``python -m simtest_funnel_mcp`` starts the server on stdio."""
2
+
3
+ from simtest_funnel_mcp.server import main
4
+
5
+ if __name__ == "__main__":
6
+ main()