Metadata-Version: 2.4
Name: crosstabs
Version: 1.4.0
Summary: MCP package with 39 statistical tools and runtime status plus 35 headless workflow tools
Project-URL: Homepage, https://crosstabs.com
Project-URL: Documentation, https://crosstabs.com
Project-URL: Source, https://pypi.org/project/crosstabs/#files
Project-URL: Support, https://crosstabs.com/support
Author-email: "crosstabs.com" <support@crosstabs.com>
License-Expression: MIT
License-File: LICENSE
Keywords: chi-square,contingency-tables,cramers-v,crosstabs,fisher-exact,mcp,model-context-protocol,odds-ratio,statistical-analysis,statistics
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: >=3.10
Requires-Dist: fastmcp>=0.1.0
Requires-Dist: mcp<2,>=1.29
Requires-Dist: numpy>=1.24.0
Requires-Dist: pandas>=2.0.0
Requires-Dist: scipy>=1.10.0
Requires-Dist: statsmodels>=0.14.0
Provides-Extra: dev
Requires-Dist: build>=1.2.2; extra == 'dev'
Requires-Dist: pip-audit>=2.9.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: tomli>=2.0.0; (python_version < '3.11') and extra == 'dev'
Description-Content-Type: text/markdown

# Crosstabs MCP Server

<!-- mcp-name: io.github.crosstabs/crosstabs -->

[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![MCP](https://img.shields.io/badge/MCP-Compatible-green.svg)](https://modelcontextprotocol.io)

This 1.4.0 distribution provides two local MCP servers: **39 statistical tools** plus one runtime-status tool (40 registered tools), and **35 headless research workflow tools** including runtime status, portable analysis plans and guided weighting. Both servers report their executing package version through `get_runtime_status`. Individual statistical tools report whether their inference is exact, asymptotic, or simulated. Publication evidence for earlier package versions does not establish this distribution's publication or certification status. Check the executing runtime rather than inferring its version from an installed plugin manifest.

Guided weighting: supply complete trusted population margins to `preview_raking_weights`, review its aggregate balance/trim/ESS diagnostics, then explicitly call `apply_raking_weights` with the reviewed fingerprint, warning acknowledgements, human approval, expected revision and idempotency key. No respondent weight vector is returned. Apply creates a new saved sampling-weight column, preserving audit/replay/undo; it grants no survey-design or ordinary-inference approval.

Both commands are local stdio servers. The package contains no HTTP/SSE
transport or cloud-deployment configuration; network transport arguments fail
closed. Use the separate five-tool public MCP at crosstabs.com only for bounded
aggregate matrices and public evidence.

`crosstabs` is an aggregate calculator. Its ordinary inferential tools require caller-attested `inputSemantics="integer_frequency_counts"` and non-negative integer frequency cells; they do not accept respondent, calibration, raking, or complex-survey weights. Use `crosstabs-headless` for a completed supported saved survey design and its disclosed design-aware inference.

Inferential aggregate calls also require `weighted=false`. The two descriptive
aggregate visual tools, `stacked_bar_data` and `correspondence_analysis`, require
`inputSemantics="descriptive_aggregate_values"`; their fractional values are not
survey-weighted inference. `mosaic_plot_data` remains an inferential residual
diagnostic and therefore requires integer frequency counts. Missing or unsupported
semantics, fractional cells, non-finite values, negative values, and unsafe integers
are rejected before any statistics are returned. `proportion_ci` separately requires
`countSemantics="integer_binomial_counts"` and safe integer binomial counts for
`successes` and `total`.

## Features

### Core Statistical Tests
| Test | Description |
|------|-------------|
| **Chi-square** | Pearson's chi-square test of independence |
| **G-test** | Likelihood-ratio alternative with an asymptotic p-value |
| **Fisher's exact** | Two-sided fixed-margin exact p-value for 2×2 integer counts |
| **McNemar's** | Exact two-sided binomial inference for fewer than 20 discordant pairs; continuity-corrected chi-square otherwise |

### Effect Sizes & Measures
| Measure | Use Case |
|---------|----------|
| **Cramér's V** | Effect size for any table size (with bias correction) |
| **Phi coefficient** | Effect size for 2×2 tables |
| **Odds ratio** | Association strength with a large-sample Woolf log interval |
| **Relative risk** | Risk comparison between groups |
| **Risk difference** | Absolute risk reduction |
| **Attributable risk** | Population-level impact |

### Ordinal Measures
| Measure | Description |
|---------|-------------|
| **Spearman's rho** | Rank correlation |
| **Kendall's tau** | Concordance measure |
| **Goodman-Kruskal gamma** | Ordinal association |
| **Somers' D** | Asymmetric ordinal measure |
| **Stuart's tau-c** | Rectangular table measure |

### Agreement & Reliability
| Measure | Description |
|---------|-------------|
| **Cohen's kappa** | Inter-rater agreement with an asymptotic normal interval |
| **Weighted kappa** | Linear/quadratic agreement with an asymptotic normal interval |

### Advanced Analysis
| Tool | Description |
|------|-------------|
| **CMH test** | Stratified analysis with a Robins-Breslow-Greenland pooled-OR interval |
| **Breslow-Day** | Test homogeneity of odds ratios |
| **Correspondence analysis** | Dimensionality reduction for tables |
| **Monte Carlo chi-square** | Fixed-margin simulated p-value estimate |
| **Power analysis** | Equal-group, two-sided normal approximation using Cohen's h |
| **Multiple comparisons** | Bonferroni and FDR corrections |

## Installation

### From PyPI (recommended)
```bash
pip install crosstabs
```

### Inspect the public source distribution
```bash
python -m pip download --no-deps --no-binary=:all: crosstabs
```

The development repository is currently private. PyPI publishes the package's
source archive; email
[support@crosstabs.com](mailto:support@crosstabs.com) for issue reports or
source-access questions.

## Quick Start

### Run the MCP Server
```bash
# Focused statistical calculators (Python 3.10+)
crosstabs

# End-to-end research workspace (Python 3.10+ and Node.js 22+)
crosstabs-headless
```

Or directly:
```bash
python -m crosstabs_mcp.server
```

### Configure an MCP client

Add to your `~/.claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "crosstabs_workspace": {
      "command": "crosstabs-headless"
    },
    "crosstabs_statistics": {
      "command": "crosstabs"
    }
  }
}
```

The headless server stores project state and generated artifacts under the local
application-data directory. Deterministic calculations stay on the machine.
It makes no hosted-AI, account, or remote-project call. Manual open-end coding
remains a browser-workspace feature rather than a local MCP operation.

### Headless workflow tools

`create_project`, `import_dataset`, `profile_dataset`, `define_row_set`,
`define_banner`, `apply_filter`, `set_weight`, `define_survey_design`,
`run_table`, `run_tab_book`,
`compare_waves`, `undo_change`, `replace_dataset`, `detect_schema_drift`, `repair_schema`,
`generate_report_pack`, `refresh_report_pack`, `export_project`,
`list_projects`, `inspect_project`, `get_audit_history`, `import_project`,
`render_project_table`, `update_variable_metadata`, `propose_transformation`,
`review_transformation`, `apply_transformation`, `undo_transformation`, and
`run_complex_survey_method`.

Project-package import is an explicit allowed-path, checksummed full-data copy.
It never overwrites a project. Rendering uses a saved table/revision/evidence ID,
not an ordinary re-analysis of caller-supplied cells. Inference-changing edits
retain approval, revision and replay guards. The local JSON store enforces
8 MiB per serialized project (including undo/audit) and 32 MiB per database
(including replay records); parser maxima are not persistence guarantees.

Mutations use expected revisions and idempotency keys. Results include structured
warnings, evidence IDs, audit records, and MCP resources for generated files.
For a detected multi-select row dimension, `define_row_set` may additionally
set `multipleResponseDenominator` to `cases` or `responses`; ordinary and
compound row sets reject that option rather than silently applying it.

### Monte Carlo workload envelope

Fixed-margin Monte Carlo accepts at most 100 rows, 100 columns, and 1,000 cells,
with a total frequency of 9,007,199,254,740,991. It admits 100,000 simulations and 20,000,000 cell-simulations.
It samples chunks of at most 512 simulations under a 32 MiB estimated numeric
peak and a 30-second server deadline.
The returned `workload` object records the admitted dimensions, cell-simulation
product, chunk size, memory estimate, memory ceiling, and deadline. The memory
estimate covers the numeric simulation path, not the MCP transport's parsed JSON
body. A supplied seed is reproducible for the same table, simulation count, and
package versions. MCP cancellation is observed between chunks; an individual
SciPy draw cannot be interrupted mid-chunk.

## Usage Examples

Once configured, Claude can perform statistical analysis:

### Chi-square Test
```
User: Test if there's an association between treatment and outcome:
      Treatment A: 50 success, 30 failure
      Treatment B: 20 success, 40 failure

Claude: [Uses chi_square_test with matrix [[50,30],[20,40]]]
        χ² = 11.67, p = 0.0006
        Cramér's V = 0.29 (small-medium effect)
        There is a significant association between treatment and outcome.
```

### Odds Ratio
```
User: Compare an adverse outcome between exposure groups:
      Exposed: 30 outcome-present, 70 outcome-absent
      Unexposed: 15 outcome-present, 85 outcome-absent

Claude: [Uses odds_ratio with matrix [[30,70],[15,85]]]
        OR = 2.43 (95% CI: 1.21-4.87)
        Exposure is associated with 143% higher odds of the outcome.
```

The epidemiology tools (`odds_ratio`, `relative_risk`, `risk_difference`, and
`attributable_risk`) use one explicit orientation:
`[[exposed outcome+, exposed outcome-], [unexposed outcome+, unexposed outcome-]]`.
They return machine-readable zero/infinite/undefined states rather than silently
continuity-correcting point estimates. Attributable/prevented fractions require
causal identification assumptions; an association alone does not establish the
counterfactual effect of removing an exposure.

### Fisher's Exact Test
```
User: I have a small sample: [[3,1],[1,5]]. Is it significant?

Claude: [Uses fishers_exact with the matrix]
        p = 0.190476 (two-tailed exact)
        Not statistically significant at α=0.05.
```

## Available Tools

| Tool Name | Description |
|-----------|-------------|
| `chi_square_test` | Chi-square test of independence |
| `g_test` | G-test (likelihood ratio) |
| `fishers_exact` | Fisher's exact test (2×2) |
| `mcnemar_test` | McNemar's test for paired data |
| `odds_ratio` | Odds ratio with CI |
| `relative_risk` | Relative risk with CI |
| `risk_difference` | Risk difference with CI |
| `cramers_v` | Cramér's V effect size |
| `phi_coefficient` | Phi for 2×2 tables |
| `cohens_kappa` | Cohen's kappa |
| `weighted_kappa` | Weighted kappa |
| `spearmans_rho` | Spearman's rank correlation |
| `kendalls_tau` | Kendall's tau-b |
| `goodman_kruskal_gamma` | Gamma coefficient |
| `somers_d` | Somers' D |
| `tau_c` | Stuart's tau-c |
| `cmh_test` | Cochran-Mantel-Haenszel |
| `breslow_day_test` | Breslow-Day test |
| `linear_trend_test` | Linear-by-linear association |
| `correspondence_analysis` | Correspondence analysis |
| `monte_carlo_chi_square` | Fixed-margin Monte Carlo p-value estimate |
| `power_analysis` | Two-sided normal-approximation power/sample size using Cohen's h |
| `bonferroni_correction` | Bonferroni p-value adjustment |
| `fdr_correction` | Benjamini-Hochberg FDR |
| `standardized_residuals` | Cell residuals |
| `post_hoc_chi_square` | Post-hoc chi-square decomposition |
| `proportion_ci` | Confidence interval for proportion |
| `check_assumptions` | Validate chi-square assumptions |
| `recommend_test` | Method suggestions with assumption caveats |
| `mosaic_plot_data` | Data for mosaic visualization |
| `stacked_bar_data` | Data for stacked bar chart |
| `attributable_risk` | Attributable risk measures |
| `chi_square_yates` | Yates' continuity correction |
| `effect_size` | Multiple contingency-table effect sizes |
| `lambda_coefficient` | Goodman–Kruskal lambda |
| `uncertainty_coefficient` | Theil's uncertainty coefficient |
| `detect_outliers` | Outlier detection |
| `crosstab_from_data` | Build table from raw data |
| `crosstab_from_csv` | Build table from CSV |

## Development

### Run Tests
```bash
pip install -e ".[dev]"
pytest tests/ -v
```

### Project Structure
```
mcp-server-python/
├── crosstabs_mcp/
│   ├── __init__.py
│   ├── headless_launcher.py # Node version check and bundled-server launcher
│   ├── headless-mcp.mjs     # Local-first 35-tool workflow MCP server
│   ├── server.py          # Main MCP server
│   └── advanced_stats.py  # Compatibility statistical kernels and contracts
├── tests/
│   ├── test_statistics.py       # Statistical behavior tests
│   └── test_reference_parity.py # Public SciPy reference parity
├── scripts/                    # Distribution verification
├── LICENSE
├── pyproject.toml
├── uv.lock
└── README.md
```

## Requirements

- Python 3.10+
- mcp >= 1.0.0
- fastmcp >= 0.1.0
- numpy >= 1.24.0
- scipy >= 1.10.0
- pandas >= 2.0.0
- statsmodels >= 0.14.0

## License

MIT License - see [LICENSE](LICENSE) for details.

## Contributing

The development repository is currently private. Send corrections and proposed
changes to [support@crosstabs.com](mailto:support@crosstabs.com).

## Links

- [PyPI package and source archive](https://pypi.org/project/crosstabs/#files)
- [Web Application](https://www.crosstabs.com)
- [Support](https://www.crosstabs.com/support)
- [MCP Documentation](https://modelcontextprotocol.io)
