Metadata-Version: 2.5
Name: spryng-analysis-mcp
Version: 0.1.1
Summary: Stdio MCP relay for Spryng Analysis — forwards authorized tool calls to your hosted Spryng endpoint.
Project-URL: Homepage, https://spryng.io/
Project-URL: Documentation, https://pypi.org/project/spryng-analysis-mcp/
Author-email: ScrumDo LLC <support@spryng.io>
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: analysis,mcp,sensemaking,spryng
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
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: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: anyio>=4.0
Requires-Dist: httpx>=0.27
Requires-Dist: mcp<3,>=2.3.0
Description-Content-Type: text/markdown

# Spryng Analysis MCP

Connect your preferred assistant to the Spryng studies you can access. This package provides a local [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) relay that forwards read-only requests to your organization's hosted Spryng Analysis service.

You need Python **3.10 or later**, a desktop MCP client that supports local stdio servers, and a Spryng organization with Analysis MCP enabled. Installing this package does not enable the service or change your study permissions.

## 1. Get your connection details

In [Spryng](https://app.spryng.io/), open your study's **Analysis → Connect your assistant**. You can also open **Organization settings → Analysis MCP** at `/organization/<organization-slug>/settings/analysis-mcp-tokens` on your Spryng app host.

Choose your assistant, create a personal token, and copy the Analysis MCP URL shown there. The token begins with `smcpa_` and is shown once. Keep it private. If setup is unavailable, ask your organization administrator to check access and enablement.

## 2. Install the relay

Choose **one** installation method. These shell examples are for macOS and Linux.

### pipx

```bash
pipx install 'spryng-analysis-mcp==0.1.1'
spryng-analysis-mcp --help
command -v spryng-analysis-mcp
```

### uv

```bash
uv tool install 'spryng-analysis-mcp==0.1.1'
spryng-analysis-mcp --help
command -v spryng-analysis-mcp
```

If the installed command is not found, follow your installer's PATH instructions and reopen your terminal.

### Python virtual environment

```bash
python3 -m venv "$HOME/.local/spryng-analysis-mcp"
"$HOME/.local/spryng-analysis-mcp/bin/python" -m pip install 'spryng-analysis-mcp==0.1.1'
"$HOME/.local/spryng-analysis-mcp/bin/spryng-analysis-mcp" --help
printf '%s\n' "$HOME/.local/spryng-analysis-mcp/bin/spryng-analysis-mcp"
```

Copy the full executable path printed by your chosen method for the next step. On Windows, use the installed executable's full Windows path in your client's configuration; the shell commands above use Unix paths.

## 3. Add Spryng to your assistant

Open your assistant's MCP settings and add a local stdio server. For clients that accept an `mcpServers` JSON configuration:

```json
{
  "mcpServers": {
    "spryng-analysis": {
      "command": "/absolute/path/to/spryng-analysis-mcp",
      "args": [
        "--url",
        "https://app.spryng.io/api/organizations/YOUR_ORGANIZATION/mcp/analysis/rpc/"
      ],
      "env": {
        "SPRYNG_ANALYSIS_MCP_TOKEN": "YOUR_PERSONAL_ANALYSIS_TOKEN"
      }
    }
  }
}
```

Replace `command` with the full executable path from installation, the URL with the exact URL from Spryng, and the token placeholder with your personal token. Do not use `~` or shell variables in `command`: desktop clients may not expand them. In Windows JSON, escape each path backslash as `\\`.

Use your client's secret storage if available. Otherwise, protect the local configuration file containing your token and never share it. Restart or reload the MCP connection after saving. Configuration formats vary by client.

## 4. Try a question

Ask your assistant:

> List the Spryng studies I can access. For one study, describe its questions and the statistics available for each.

Then:

> Show a supported statistic for one question, explain any missing-answer or privacy limits, and identify the study and question behind it.

Successful tool discovery and an answer grounded in returned study data confirm the assistant connection. Spryng's **Check Spryng readiness** checks server readiness; it does not prove that an external assistant is connected.

For the **virtual-environment installation above**, you can also check server connectivity from a terminal:

```bash
export SPRYNG_ANALYSIS_MCP_URL='YOUR_ANALYSIS_MCP_URL'
export SPRYNG_ANALYSIS_MCP_TOKEN='YOUR_PERSONAL_ANALYSIS_TOKEN'
"$HOME/.local/spryng-analysis-mcp/bin/python" -m spryng_analysis_mcp.connection_check
```

Exit code `0` means MCP initialization and tool discovery succeeded. It does not test a model's reasoning. With pipx or uv, verify discovery in your assistant; the package is isolated from your system Python.

## Where data goes

| Component | What it does |
| --- | --- |
| Hosted Spryng | Stores study data and enforces authorization, redaction, and privacy limits. Requests still reach Spryng even when your model runs locally. |
| This relay | Runs on your computer and forwards calls to the configured Spryng Analysis URL. It does not include or start an AI model. |
| Local model | Requires a separately configured model runtime and a client capable of calling MCP tools. Model compatibility and answer quality depend on that setup. |
| Cloud assistant | May send prompts and returned study data to its model provider. Check your organization's policy and that provider's settings before connecting. |
| Institution or regional setup | Requires an administrator-approved model endpoint and client configuration. Installing this relay does not provision a regional service, certify residency, or isolate a model's network traffic. |

The relay does not choose a model or fall back to a cloud model. It sends the token only to the configured, validated Analysis URL, rejects HTTP redirects, ignores environment proxy settings, and does not persist the token itself. Your assistant's configuration, conversation history, and model runtime have their own storage and network behavior.

Available tools and statistics come from your Spryng server. Do not treat a missing answer as a refusal or average a three-part answer as if it were a slider. Review source evidence and the usage rules returned with statistics before relying on an assistant's interpretation.

## Revoke access or troubleshoot

In **Organization settings → Analysis MCP → Manage tokens**, revoke a token to deny subsequent requests using it. Also remove it from your assistant's configuration.

| Symptom | What to check |
| --- | --- |
| Executable not found | Use the full installed executable path in `command`, rather than relying on the desktop app's PATH. |
| Missing `SPRYNG_ANALYSIS_MCP_TOKEN` | Put the token in the MCP client's server environment or secret settings. A terminal export alone may not reach a desktop app. |
| 401 or 403 | Check for a revoked token, the wrong organization URL, or missing access. Create a replacement token only if needed. |
| Endpoint unavailable | Check that Analysis MCP is enabled for your organization and that you copied its current URL. |
| Wrong endpoint or redirect | Use the exact HTTPS Analysis URL ending in `/mcp/analysis/rpc/`; board MCP and story-collection URLs are different services. |
| Tools appear but answers are unsupported | Confirm that your client and model support tool calls. Ask for source evidence and compare the answer with the returned data. |

Contact [support@spryng.io](mailto:support@spryng.io) with the package version, client name, and error message. Remove tokens and participant data before sharing diagnostics. Learn more at [Spryng](https://spryng.io/).

## License

This connector is licensed under the [Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0). Copyright 2026 ScrumDo LLC. The full `LICENSE` and attribution `NOTICE` are included in the distribution.

The license does not grant trademark rights, except for the reasonable and customary use needed to describe the origin of the work and reproduce the `NOTICE`, as provided in Section 6. This license covers the connector; it does not grant access to hosted Spryng services.
