choson-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,26 @@
1
+ # Publish to PyPI when a version tag (v*) is pushed. Uses PyPI trusted publishing: no token in the repo. Needs a
2
+ # trusted publisher on pypi.org for this repo, workflow publish.yml, environment pypi.
3
+ name: publish
4
+ on:
5
+ push:
6
+ tags: ["v*"]
7
+ jobs:
8
+ build:
9
+ runs-on: ubuntu-latest
10
+ steps:
11
+ - uses: actions/checkout@v4
12
+ - uses: actions/setup-python@v5
13
+ with: {python-version: "3.12"}
14
+ - run: python -m pip install build && python -m build
15
+ - uses: actions/upload-artifact@v4
16
+ with: {name: dist, path: dist/}
17
+ publish:
18
+ needs: build
19
+ runs-on: ubuntu-latest
20
+ environment: pypi
21
+ permissions:
22
+ id-token: write
23
+ steps:
24
+ - uses: actions/download-artifact@v4
25
+ with: {name: dist, path: dist/}
26
+ - uses: pypa/gh-action-pypi-publish@release/v1
@@ -0,0 +1,6 @@
1
+ __pycache__/
2
+ *.egg-info/
3
+ dist/
4
+ build/
5
+ .venv/
6
+ .env
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Mark Shipman
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,61 @@
1
+ Metadata-Version: 2.5
2
+ Name: choson-mcp
3
+ Version: 0.1.0
4
+ Summary: MCP server for the Chosŏn conjoint API: run studies from Claude or any MCP client
5
+ Project-URL: Homepage, https://quantecarlo.com
6
+ Project-URL: Documentation, https://quantecarlo.com/api.md
7
+ Project-URL: Source, https://github.com/sign-of-fourier/choson-mcp
8
+ License-Expression: MIT
9
+ License-File: LICENSE
10
+ Requires-Python: >=3.10
11
+ Requires-Dist: httpx>=0.27
12
+ Requires-Dist: mcp<2,>=1.20
13
+ Description-Content-Type: text/markdown
14
+
15
+ # choson-mcp
16
+
17
+ An MCP server for the Chosŏn conjoint API: upload survey data, fit, read results and run the simulators from Claude
18
+ (Claude Code, Claude Desktop) or any MCP client. It runs on your machine and calls `https://quantecarlo.com/api/v1`
19
+ with your API key. Paid Chosŏn plans.
20
+
21
+ ## Set up
22
+
23
+ 1. Create an API key: sign in at https://quantecarlo.com/app/, click API, Create key.
24
+ 2. Add the server.
25
+
26
+ Claude Code:
27
+
28
+ ```bash
29
+ claude mcp add choson -e CHOSON_API_KEY=chs_... -- uvx choson-mcp
30
+ ```
31
+
32
+ Claude Desktop (`claude_desktop_config.json`):
33
+
34
+ ```json
35
+ {"mcpServers": {"choson": {"command": "uvx", "args": ["choson-mcp"], "env": {"CHOSON_API_KEY": "chs_..."}}}}
36
+ ```
37
+
38
+ Until the package is on PyPI, install from GitHub instead: replace `uvx choson-mcp` with
39
+ `uvx --from git+https://github.com/sign-of-fourier/choson-mcp choson-mcp` (in the Desktop config, args
40
+ `["--from", "git+https://github.com/sign-of-fourier/choson-mcp", "choson-mcp"]`).
41
+
42
+ The API itself is documented at https://quantecarlo.com/api.md.
43
+
44
+ ## Tools
45
+
46
+ whoami, list_projects, create_project, get_project, upload_data (a local file), get_dataset, set_design,
47
+ quote_fit (hardware, estimate and the 2-hour maximum, nothing queued), start_fit, fit_status, wait_for_fit,
48
+ cancel_fit, get_result (whole or one section), download (per-respondent CSV, workbook, Excel simulator),
49
+ simulate_shares, simulate_removal (diversion), price_sweep, elasticities, forecast, api_reference (the full API
50
+ reference) and call_api (any other /v1 route: range, recommend, test-next, optimize, segments, the menu, MaxDiff,
51
+ volumetric and claims tools, survey design).
52
+
53
+ The server asks the assistant to show you the hardware, estimate and maximum from quote_fit and get your go-ahead
54
+ before starting a fit. Every fit is stopped at 2 hours by the platform.
55
+
56
+ ## Environment
57
+
58
+ | variable | default |
59
+ |---|---|
60
+ | `CHOSON_API_KEY` | required |
61
+ | `CHOSON_API_URL` | `https://quantecarlo.com/api/v1` |
@@ -0,0 +1,47 @@
1
+ # choson-mcp
2
+
3
+ An MCP server for the Chosŏn conjoint API: upload survey data, fit, read results and run the simulators from Claude
4
+ (Claude Code, Claude Desktop) or any MCP client. It runs on your machine and calls `https://quantecarlo.com/api/v1`
5
+ with your API key. Paid Chosŏn plans.
6
+
7
+ ## Set up
8
+
9
+ 1. Create an API key: sign in at https://quantecarlo.com/app/, click API, Create key.
10
+ 2. Add the server.
11
+
12
+ Claude Code:
13
+
14
+ ```bash
15
+ claude mcp add choson -e CHOSON_API_KEY=chs_... -- uvx choson-mcp
16
+ ```
17
+
18
+ Claude Desktop (`claude_desktop_config.json`):
19
+
20
+ ```json
21
+ {"mcpServers": {"choson": {"command": "uvx", "args": ["choson-mcp"], "env": {"CHOSON_API_KEY": "chs_..."}}}}
22
+ ```
23
+
24
+ Until the package is on PyPI, install from GitHub instead: replace `uvx choson-mcp` with
25
+ `uvx --from git+https://github.com/sign-of-fourier/choson-mcp choson-mcp` (in the Desktop config, args
26
+ `["--from", "git+https://github.com/sign-of-fourier/choson-mcp", "choson-mcp"]`).
27
+
28
+ The API itself is documented at https://quantecarlo.com/api.md.
29
+
30
+ ## Tools
31
+
32
+ whoami, list_projects, create_project, get_project, upload_data (a local file), get_dataset, set_design,
33
+ quote_fit (hardware, estimate and the 2-hour maximum, nothing queued), start_fit, fit_status, wait_for_fit,
34
+ cancel_fit, get_result (whole or one section), download (per-respondent CSV, workbook, Excel simulator),
35
+ simulate_shares, simulate_removal (diversion), price_sweep, elasticities, forecast, api_reference (the full API
36
+ reference) and call_api (any other /v1 route: range, recommend, test-next, optimize, segments, the menu, MaxDiff,
37
+ volumetric and claims tools, survey design).
38
+
39
+ The server asks the assistant to show you the hardware, estimate and maximum from quote_fit and get your go-ahead
40
+ before starting a fit. Every fit is stopped at 2 hours by the platform.
41
+
42
+ ## Environment
43
+
44
+ | variable | default |
45
+ |---|---|
46
+ | `CHOSON_API_KEY` | required |
47
+ | `CHOSON_API_URL` | `https://quantecarlo.com/api/v1` |
File without changes
@@ -0,0 +1,250 @@
1
+ """Chosŏn MCP server (stdio): the public /v1 API as tools for Claude or any MCP client.
2
+
3
+ Configure with CHOSON_API_KEY (required) and CHOSON_API_URL (default https://quantecarlo.com/api/v1). The full API
4
+ reference is the resource choson://docs and the tool api_reference.
5
+ """
6
+ from __future__ import annotations
7
+
8
+ import logging
9
+ import os
10
+ import time
11
+ from pathlib import Path
12
+ from typing import Any
13
+
14
+ import httpx
15
+ from mcp.server.fastmcp import FastMCP
16
+
17
+ BASE = os.environ.get("CHOSON_API_URL", "https://quantecarlo.com/api/v1").rstrip("/")
18
+ DOCS_URL = os.environ.get("CHOSON_DOCS_URL", "https://quantecarlo.com/api.md")
19
+ logging.getLogger("httpx").setLevel(logging.WARNING) # request lines would flood the client's log
20
+ MAX_WAIT = 600 # longest a single wait_for_fit call blocks, seconds
21
+ FIT_CAP_HOURS = 2 # every fit is stopped at 2 hours by the platform
22
+
23
+ mcp = FastMCP("choson", instructions=(
24
+ "Chosŏn runs conjoint studies (CBC, menu-based, MaxDiff, pricing, claims tests, volumetric). Flow: create_project "
25
+ "-> upload_data -> check the report and design (set_design if the inferred design is wrong) -> start_fit -> "
26
+ "quote_fit -> start_fit -> wait_for_fit -> get_result -> simulators. Before start_fit, call quote_fit with the "
27
+ "same settings, tell the user the hardware, the estimated time and the maximum (every fit stops at 2 hours), "
28
+ "and get their go-ahead. Report estimates with their 95% "
29
+ "ranges; read fit warnings before drawing conclusions. For anything not covered by a tool, read api_reference "
30
+ "and use call_api."))
31
+
32
+
33
+ class ApiError(Exception):
34
+ pass
35
+
36
+
37
+ def _client() -> httpx.Client:
38
+ key = os.environ.get("CHOSON_API_KEY", "").strip()
39
+ if not key:
40
+ raise ApiError("CHOSON_API_KEY is not set. Create a key at https://quantecarlo.com/app/#/keys (paid plans) "
41
+ "and set it in this server's environment.")
42
+ return httpx.Client(base_url=BASE, headers={"Authorization": f"Bearer {key}",
43
+ "User-Agent": "choson-mcp/0.1"}, timeout=120)
44
+
45
+
46
+ def _req(method: str, path: str, *, json_body: Any = None, files=None, data=None, raw: bool = False):
47
+ with _client() as c:
48
+ r = c.request(method, path if path.startswith("/") else "/" + path, json=json_body, files=files, data=data)
49
+ if r.status_code >= 400:
50
+ try:
51
+ d = r.json().get("detail")
52
+ except ValueError:
53
+ d = r.text
54
+ if isinstance(d, dict):
55
+ d = "; ".join(str(x) for x in [d.get("message")] + list(d.get("problems") or []) + list(d.get("errors") or []) if x)
56
+ elif isinstance(d, list):
57
+ d = "; ".join(e.get("msg", str(e)) for e in d)
58
+ raise ApiError(f"{r.status_code}: {d}")
59
+ if raw:
60
+ return r.content
61
+ return r.json() if r.content else None
62
+
63
+
64
+ # ---------------------------------------------------------------------------------------------------------- reference
65
+ @mcp.resource("choson://docs")
66
+ def docs() -> str:
67
+ """The Chosŏn API reference (v1)."""
68
+ return httpx.get(DOCS_URL, timeout=30).text
69
+
70
+
71
+ @mcp.tool()
72
+ def api_reference() -> str:
73
+ """The full Chosŏn API reference: data formats for every module, fit settings, the results JSON, every
74
+ simulator and search with its fields, errors. Read it before call_api or when a format is unclear."""
75
+ return docs()
76
+
77
+
78
+ @mcp.tool()
79
+ def whoami() -> dict:
80
+ """The account's plan and its limits (respondents, products, tasks, queued jobs) and GPU minutes this month."""
81
+ return _req("GET", "/me")
82
+
83
+
84
+ # ----------------------------------------------------------------------------------------------------- projects, data
85
+ @mcp.tool()
86
+ def list_projects() -> list:
87
+ """All projects on the account (id, name, kind)."""
88
+ return _req("GET", "/projects")
89
+
90
+
91
+ @mcp.tool()
92
+ def create_project(name: str, kind: str = "cbc") -> dict:
93
+ """Create a project. kind: cbc, mbc, maxdiff, pricing, concept or volumetric."""
94
+ return _req("POST", "/projects", json_body={"name": name, "kind": kind})
95
+
96
+
97
+ @mcp.tool()
98
+ def get_project(project_id: str) -> dict:
99
+ """A project with its datasets and fits."""
100
+ return _req("GET", f"/projects/{project_id}")
101
+
102
+
103
+ @mcp.tool()
104
+ def upload_data(project_id: str, responses_path: str, design_path: str | None = None) -> dict:
105
+ """Upload a responses file from the local disk (CSV in the module's long format, or a Sawtooth .CHO for CBC;
106
+ see api_reference for formats). Optional design JSON for CBC. Returns the dataset: its id, the validation report
107
+ (errors must be fixed before fitting; read warnings) and, for CBC, the design (check design_inferred)."""
108
+ p = Path(responses_path).expanduser()
109
+ files = {"responses": (p.name, p.read_bytes())}
110
+ if design_path:
111
+ d = Path(design_path).expanduser()
112
+ files["design"] = (d.name, d.read_bytes(), "application/json")
113
+ return _req("POST", f"/projects/{project_id}/data", files=files)
114
+
115
+
116
+ @mcp.tool()
117
+ def get_dataset(dataset_id: str) -> dict:
118
+ """A dataset: validation report, summary, design."""
119
+ return _req("GET", f"/datasets/{dataset_id}")
120
+
121
+
122
+ @mcp.tool()
123
+ def set_design(dataset_id: str, design: dict) -> dict:
124
+ """CBC: replace the dataset's design (attributes with name, levels, kind categorical / linear; none; price) and
125
+ re-run the checks. Start from the design get_dataset returns and edit it."""
126
+ return _req("PUT", f"/datasets/{dataset_id}/design", json_body=design)
127
+
128
+
129
+ # --------------------------------------------------------------------------------------------------------------- fits
130
+ @mcp.tool()
131
+ def quote_fit(dataset_id: str, settings: dict | None = None) -> dict:
132
+ """What a fit with these settings would run on, without queuing it: compute (cpu, modal_cpu, t4, h100),
133
+ estimated_seconds, max_seconds (every fit is stopped at 7,200 s = 2 hours) and any notes. Same settings as
134
+ start_fit. Show the user this before starting a fit."""
135
+ return _req("POST", f"/datasets/{dataset_id}/fits", json_body={**(settings or {}), "dry_run": True})
136
+
137
+
138
+ @mcp.tool()
139
+ def start_fit(dataset_id: str, settings: dict | None = None) -> dict:
140
+ """Queue a fit. settings (all optional, see api_reference): taste (none / diagonal / full), error_shares (list of
141
+ attributes), holdout (last / none), hb_baseline, constraints, covariates, classes, compute (auto / cpu / t4 /
142
+ h100). Returns the fit with compute (the hardware chosen) and progress.estimated_seconds. Every fit stops at 2
143
+ hours. Call quote_fit first, show the user the hardware, the estimate and the 2-hour maximum, and get their
144
+ go-ahead."""
145
+ return _req("POST", f"/datasets/{dataset_id}/fits", json_body={**(settings or {}), "dry_run": False})
146
+
147
+
148
+ @mcp.tool()
149
+ def fit_status(fit_id: str) -> dict:
150
+ """A fit's status (queued, running, done, failed, cancelled), progress stage, error and timestamps."""
151
+ return _req("GET", f"/fits/{fit_id}")
152
+
153
+
154
+ @mcp.tool()
155
+ def wait_for_fit(fit_id: str, max_seconds: int = 300) -> dict:
156
+ """Poll a fit until it is done, failed or cancelled, or max_seconds pass (at most 600; call again to keep
157
+ waiting). Returns the last status."""
158
+ end = time.time() + min(max(5, max_seconds), MAX_WAIT)
159
+ while True:
160
+ f = _req("GET", f"/fits/{fit_id}")
161
+ if f["status"] in ("done", "failed", "cancelled") or time.time() >= end:
162
+ return f
163
+ time.sleep(5)
164
+
165
+
166
+ @mcp.tool()
167
+ def cancel_fit(fit_id: str) -> dict:
168
+ """Cancel a queued fit at once or a running one within seconds."""
169
+ return _req("POST", f"/fits/{fit_id}/cancel")
170
+
171
+
172
+ @mcp.tool()
173
+ def get_result(fit_id: str, section: str | None = None) -> Any:
174
+ """The results JSON of a finished fit. Large; pass section to get one part: derived (part-worths, importances,
175
+ WTP), params (mean tastes, taste spread, error shares), fit (log-likelihood, holdout hit rate, warnings),
176
+ baselines (comparison models), meta (settings, design). Every estimate is {est, se, lo, hi} with a 95% range."""
177
+ r = _req("GET", f"/fits/{fit_id}/result")
178
+ if section:
179
+ if section not in r:
180
+ raise ApiError(f"no section {section!r}; sections: {', '.join(r)}")
181
+ return r[section]
182
+ return r
183
+
184
+
185
+ @mcp.tool()
186
+ def download(fit_id: str, what: str, save_to: str) -> str:
187
+ """Save a fit's file to the local disk. what: respondents.csv (per-respondent estimates), workbook.xlsx (the
188
+ study workbook) or excel-simulator.xlsx (CBC, needs the Chosŏn Excel add-in)."""
189
+ if what not in ("respondents.csv", "workbook.xlsx", "excel-simulator.xlsx"):
190
+ raise ApiError("what must be respondents.csv, workbook.xlsx or excel-simulator.xlsx")
191
+ out = Path(save_to).expanduser()
192
+ if out.is_dir():
193
+ out = out / f"{fit_id}-{what}"
194
+ out.write_bytes(_req("GET", f"/fits/{fit_id}/{what}", raw=True))
195
+ return str(out)
196
+
197
+
198
+ # --------------------------------------------------------------------------------------------------- CBC simulators
199
+ @mcp.tool()
200
+ def simulate_shares(fit_id: str, products: list[dict], group: str | None = None) -> dict:
201
+ """Share of preference for a shelf, with 95% ranges. products: up to 60, each {attribute: level} with levels
202
+ exactly as in the design (price any number in the tested range). group: a covariate group, if the fit has them."""
203
+ return _req("POST", f"/fits/{fit_id}/simulate", json_body={"products": products, "group": group})
204
+
205
+
206
+ @mcp.tool()
207
+ def simulate_removal(fit_id: str, products: list[dict], remove: int, group: str | None = None) -> dict:
208
+ """Remove one product (0-based index into products): the shares after, and where its buyers go (diversion to
209
+ each remaining product and to none), with 95% ranges. The substitution question."""
210
+ return _req("POST", f"/fits/{fit_id}/simulate/remove", json_body={"products": products, "remove": remove, "group": group})
211
+
212
+
213
+ @mcp.tool()
214
+ def price_sweep(fit_id: str, products: list[dict], product: int, prices: list[float] | None = None) -> dict:
215
+ """Shares as one product's (0-based index) price moves across the tested range (or the given prices)."""
216
+ return _req("POST", f"/fits/{fit_id}/simulate/price-sweep", json_body={"products": products, "product": product, "prices": prices})
217
+
218
+
219
+ @mcp.tool()
220
+ def elasticities(fit_id: str, products: list[dict]) -> dict:
221
+ """Own- and cross-price elasticities for a shelf, with 95% ranges."""
222
+ return _req("POST", f"/fits/{fit_id}/simulate/elasticities", json_body={"products": products})
223
+
224
+
225
+ @mcp.tool()
226
+ def forecast(fit_id: str, request: dict) -> dict:
227
+ """Units, revenue and profit with 95% ranges, the change against a base shelf and the chance of clearing a
228
+ hurdle. request: products, occasions, prices, unit_costs, own (indexes), optional base and hurdle (see
229
+ api_reference)."""
230
+ return _req("POST", f"/fits/{fit_id}/simulate/forecast", json_body=request)
231
+
232
+
233
+ # ------------------------------------------------------------------------------------------------------- everything
234
+ @mcp.tool()
235
+ def call_api(method: str, path: str, body: dict | None = None) -> Any:
236
+ """Any other /v1 route (see api_reference): searches (range, recommend, test-next; queued, poll with GET on the
237
+ same path), optimize, segments, MBC / MaxDiff / volumetric / concept tools, survey design. path is relative to
238
+ /v1, e.g. "/fits/abc123/range". JSON only; use upload_data and download for files."""
239
+ method = method.upper()
240
+ if method not in ("GET", "POST", "PUT", "DELETE"):
241
+ raise ApiError("method must be GET, POST, PUT or DELETE")
242
+ return _req(method, path, json_body=body if method != "GET" else None)
243
+
244
+
245
+ def main():
246
+ mcp.run()
247
+
248
+
249
+ if __name__ == "__main__":
250
+ main()
@@ -0,0 +1,21 @@
1
+ [project]
2
+ name = "choson-mcp"
3
+ version = "0.1.0"
4
+ description = "MCP server for the Chosŏn conjoint API: run studies from Claude or any MCP client"
5
+ readme = "README.md"
6
+ license = "MIT"
7
+ license-files = ["LICENSE"]
8
+ requires-python = ">=3.10"
9
+ dependencies = ["mcp>=1.20,<2", "httpx>=0.27"]
10
+
11
+ [project.urls]
12
+ Homepage = "https://quantecarlo.com"
13
+ Documentation = "https://quantecarlo.com/api.md"
14
+ Source = "https://github.com/sign-of-fourier/choson-mcp"
15
+
16
+ [project.scripts]
17
+ choson-mcp = "choson_mcp.server:main"
18
+
19
+ [build-system]
20
+ requires = ["hatchling"]
21
+ build-backend = "hatchling.build"