# Survey Solutions MCP Server

Codex-ready local MCP server for Survey Solutions Headquarters workflows.

This package runs as a local `stdio` MCP server. It lets Codex inspect Survey Solutions servers, manage local connection profiles, run safe read workflows, download and inspect exports, and perform guarded fieldwork/admin actions when the local profile permission level allows it.

## Status

- Version: `0.2.7`
- Runtime: Node.js 20+
- MCP transport: local `stdio`
- Default profile: mock Survey Solutions server for local testing
- Implemented tools: 123
- Prompts: 6
- Resources: 2
- Current target clients: Codex / OpenAI MCP clients and Claude Desktop local MCP
- Developed and tested against Survey Solutions Headquarters server version `26.07`
- Current scope: curated public API surface for Headquarters discovery, fieldwork operations, exports/version workflows, setup helpers, administration, statistics, and modular QC planning.
- License: MIT

## What It Can Do

- Manage local Survey Solutions connection profiles with `suso-mcp`.
- Warn about duplicate live profiles and provide cleanup commands.
- Explain permission modes and recommend the least-permissive mode for a task.
- List workspaces, questionnaires, assignments, interviews, users, and export jobs.
- Normalize MCP pagination metadata across Survey Solutions endpoints that mix zero-based and one-based offsets.
- Start, inspect, download, and summarize export files.
- Return race-aware export cancellation envelopes with refreshed job state.
- Activate/deactivate web interview mode and create web-link assignments.
- Read interview details/history/stats/PDFs.
- Add interview comments and perform approval/rejection actions with explicit confirmations.
- Run guarded workspace/user/settings admin actions.
- Use GraphQL read queries and raw REST escape hatches when explicitly enabled.
- Report runtime diagnostics including package version, build timestamp, config path, active profile, and commit SHA when available, with a non-null fallback for source archives.
- Guide Codex or Claude Desktop through a named web-test workflow after manual questionnaire import: check/create test users, activate web mode, create a web assignment, and return the link.

## Scope Notes

`get_api_capabilities` may report many REST operations from the active Headquarters Swagger/OpenAPI document. This is the standard server REST API description, not an OpenAI-specific spec, and it is useful for both Codex/OpenAI MCP clients and Claude Desktop. Version 0.2.7 keeps curated tools tied to endpoints confirmed in the tested Survey Solutions 26.07 public OpenAPI document, with raw discovery tools available for future documented endpoints.

`get_tool_catalog` includes `requiredEndpoint`, `availability`, `verifiedOnCurrentServer`, and `unavailableReason` fields for curated tools backed by a REST endpoint. Use it to distinguish a tool that is unsupported by the connected Headquarters build from a real missing assignment, questionnaire, or user.

Use curated tools first. Raw REST/GraphQL is deliberately gated and should stay disabled for ordinary AI-agent use. Raw API access is useful for advanced endpoint testing, but it does not provide the same guardrails, confirmations, permission explanations, or workflow guidance as curated tools.

Map and calendar wrappers were removed from the curated surface in v0.2.6 because no matching public REST/GraphQL guide or tested 26.07 OpenAPI endpoints were found. If a future Headquarters build documents those operations, use `get_api_capabilities`, `openapi_operation`, or guarded raw API testing before adding curated wrappers back.

## Install

From a release zip or GitHub checkout:

```powershell
npm install
npm run build
npm run smoke
npm link
```

On Windows, the easiest path is:

```text
install-and-setup.bat
```

That installer checks Node/npm, installs dependencies, builds, runs smoke tests, links the commands, and optionally walks through live Survey Solutions profile setup.

## Windows Helper Launchers

After running the installer once, these helper files provide a neat click-through way to change local runtime settings:

- `switch-profile.bat`: lists profiles, sets the chosen profile as active/default, and tests it.
- `change-permission.bat`: lists profiles, changes a profile permission level, and disables raw API flags when resetting to `read_only`.
- `uninstall-mcp.bat`: unlinks the global commands, checks for currently running MCP node processes, and shows the Codex/Claude config cleanup steps. It preserves local profiles unless run with `-RemoveProfiles`.

Restart Codex after adding or changing the MCP config. Also restart Codex after changing the active profile or permission level if the MCP server was already loaded.

## Codex MCP Setup

After installation, add this MCP server to Codex/OpenAI MCP configuration. In Codex (ChatGPT Desktop), go to Settings > Plugins > MCPs and enter:

```json
{
  "mcpServers": {
    "survey-solutions": {
      "type": "stdio",
      "command": "survey-solutions-mcp",
      "args": []
    }
  }
}
```

If your client requires a direct Node path instead of the linked command:

```json
{
  "mcpServers": {
    "survey-solutions": {
      "type": "stdio",
      "command": "node",
      "args": [
        "C:/path/to/survey-solutions-mcp/dist/index.js"
      ]
    }
  }
}
```

Do not put Survey Solutions URLs, usernames, passwords, or tokens in the MCP launch config. Store those through the local profile CLI.

Restart Codex after saving or changing the MCP config so it reloads the local server definition.

## Claude Desktop MCP Setup

In Claude Desktop, go to Settings > Developer > Edit Config. This opens `claude_desktop_config.json`.

Add the Survey Solutions server under `mcpServers` using the direct Node path:

```json
{
  "mcpServers": {
    "survey-solutions": {
      "command": "node",
      "args": [
        "C:\\path\\to\\survey-solutions-mcp\\dist\\index.js"
      ]
    }
  }
}
```

Replace the path with the folder where this package was extracted. If your config already has other keys such as `preferences`, keep them and only add the `survey-solutions` block inside the existing `mcpServers` object. Claude Desktop does not need the Codex/OpenAI `"type": "stdio"` field.

Restart Claude Desktop after saving or changing the config so it reloads the local server definition.

## Cleanup / Uninstall

Old extracted copies are mostly harmless if Codex and Claude Desktop no longer reference them. They can become confusing if multiple MCP client config entries point at old package folders, because the client may launch stale server versions.

To clean up the global command link and get guided client-config cleanup steps, double-click:

```text
uninstall-mcp.bat
```

The cleanup helper does not delete `C:\Users\<you>\.suso-mcp\config.json` by default, because that file may contain profiles you want to reuse with the next version. To remove local profile config as well, run:

```powershell
powershell -ExecutionPolicy Bypass -File .\uninstall-mcp.ps1 -RemoveProfiles
```

## Profile CLI

List profiles:

```powershell
suso-mcp profile list
```

Test the built-in mock profile:

```powershell
suso-mcp profile test mock
```

Add a live profile with basic auth:

```powershell
suso-mcp profile add test-server `
  --server-url "https://YOUR-SERVER.mysurvey.solutions" `
  --workspace "primary" `
  --auth basic `
  --username "api_user" `
  --password "api_password" `
  --permission read_only
```

Add a live profile with bearer/token auth:

```powershell
suso-mcp profile add test-server `
  --server-url "https://YOUR-SERVER.mysurvey.solutions" `
  --workspace "primary" `
  --auth token `
  --token "YOUR_TOKEN" `
  --permission read_only
```

Set the active/default profile:

```powershell
suso-mcp profile set-default test-server
suso-mcp profile test test-server
```

Remove a duplicate local profile after choosing the canonical one:

```powershell
suso-mcp profile delete old-profile-name --yes
```

## First Codex Prompt

```text
Use the Survey Solutions MCP. Call survey_solutions_orientation, get_tool_catalog, list_profiles, get_mcp_diagnostics, check_connection, and list_questionnaires.
```

The mock profile should work immediately. Switch to a live profile only after `suso-mcp profile test <name>` succeeds.

## Permissions

Profiles start as `read_only`. Raise permissions only for the exact action you intend to run:

```powershell
suso-mcp profile permission test-server fieldwork_write
suso-mcp profile permission test-server admin_write
suso-mcp profile permission test-server read_only
```

Raw API access is separately controlled:

```powershell
suso-mcp profile raw-api test-server enable-get
suso-mcp profile raw-api test-server enable-writes
suso-mcp profile raw-api test-server enable-delete
suso-mcp profile raw-api test-server enable-graphql-mutations
suso-mcp profile raw-api test-server disable
```

## Development

```powershell
npm install
npm run check
npm run build
npm run audit:openapi
npm run smoke
```

Release packaging is a plain source package with `dist`, docs, installer scripts, and `user-pack` included. The generated zip should exclude `node_modules`, local `.suso-*` folders, temporary files, and user config/secrets.

## License

MIT. See `LICENSE`.

## Documentation

- `user-pack/README.md`: end-user Codex setup and tool list.
- `user-pack/LOCAL_COMPUTER_SETUP.md`: step-by-step Windows setup.
- `user-pack/TEST_CHECKLIST.md`: mock/live/write testing checklist.
- `docs/WRITE_TOOL_GUARDRAILS.md`: permission and write-action safety notes.
- `docs/MVP_BACKLOG.md`: remaining product backlog.
- `docs/GITHUB_UPLOAD_CHECKLIST.md`: first public GitHub upload checklist.
- `SECURITY.md`: credential and raw-API safety notes.