npm package: @insightology.ai/imra-data-service-mcp
Description: MCP server for the Insightology IMRA Data Service
Latest version: 0.0.4

# IMRA Data Service MCP Server

A Model Context Protocol (MCP) server that exposes the **Insightology IMRA (Interview Management and Research Analysis) Data Service** API as tools. It lets AI assistants (e.g. Cursor) manage organisations, clients, projects, briefs, interviews, discussion guides, spend data, and analyzer runs through a single MCP interface.

## Features

This MCP server provides **read**, **list**, **create**, **update**, and **delete** tools for every domain entity:

- **Get-by-ID tools** – Fetch a single resource by ID (brief, project, client, organisation, interview, interview guide, interview session, interview invitation, discussion guide, organisation member, organisation invitation, analyzer run, analyzer run file/response/conversation/insight, spend, brief source).
- **List tools** – List resources by parent (e.g. briefs by project, interviews by project, clients by organisation, projects by organisation or client, discussion guides by project or brief, etc.).
- **Special list tools** – `list_organisations`, `list_interviews_open_to_all`, `list_briefs` (with pagination), `search_projects_by_organisation_and_client`.
- **Create / update / delete tools** – Named tools for each entity (e.g. `create_brief`, `update_brief`, `delete_brief`; `create_project`, `update_project`, `delete_project`; and so on for organisation, client, brief source, spend, discussion guide, interview guide, interview, interview session, interview invitation, analyzer run, analyzer run file/response/conversation/insight).

Responses are returned as markdown with JSON where applicable.

## Installation

```bash
npm install
```

## Building

```bash
npm run build
```

This compiles TypeScript with `tsc` and writes output to `dist/`. Use this before running the server or publishing.

## Development

```bash
# Build the project
npm run build

# Run the compiled server (requires base URL)
node dist/index.js <imra-data-service-url> [api-key]

# Or run from source with tsx
npm run dev
```

**Note:** `npm run dev` runs `tsx src/index.ts` without arguments; you must configure the IMRA base URL via config or pass it when invoking the server (e.g. in Cursor MCP args).

## Usage with npx

After building and publishing to npm:

```bash
npx @insightology.ai/imra-data-service-mcp <imra-data-service-url> [api-key]
```

**Examples:**

```bash
# Without API key
npx @insightology.ai/imra-data-service-mcp http://localhost:3000

# With API key
npx @insightology.ai/imra-data-service-mcp http://localhost:3000 your-api-key
```

### Command-line arguments

- **`<imra-data-service-url>`** (required): Base URL of the IMRA Data Service (e.g. `http://localhost:3000`). Paths such as `/api/brief`, `/api/project`, etc. are appended to this URL.
- **`[api-key]`** (optional): API key sent in the `X-API-Key` header when provided.

Paths are automatically prefixed with `/api`. For example, with base URL `http://localhost:3000`, a request to the `brief` resource uses `http://localhost:3000/api/brief`.

## Adding to Cursor

1. Open **Settings** → **Features** → **Model Context Protocol** → **Servers**.
2. Add a server entry, for example:

```json
{
  "mcpServers": {
    "imra-data-service": {
      "command": "npx",
      "args": [
        "@insightology.ai/imra-data-service-mcp",
        "http://localhost:3000"
      ]
    }
  }
}
```

Replace `http://localhost:3000` with your IMRA Data Service URL. If the service requires an API key, add it as the third element in `args` or use env (see below).

### Using environment variables

To avoid putting the URL or API key in the config file:

```json
{
  "mcpServers": {
    "imra-data-service": {
      "command": "npx",
      "args": ["@insightology.ai/imra-data-service-mcp"],
      "env": {
        "imra-data-service__url": "http://localhost:3000",
        "imra-data-service__apiKey": "your-api-key-here"
      }
    }
  }
}
```

3. Restart Cursor so the MCP server loads.

## MCP tools overview

Read, list, create, update, and delete are exposed as separate named tools per entity.

### Get-by-ID tools

Return a single resource by ID:

`get_brief`, `get_project`, `get_client`, `get_organisation`, `get_interview`, `get_interview_guide`, `get_interview_session`, `get_interview_invitation`, `get_discussion_guide`, `get_organisation_member`, `get_organisation_invitation`, `get_analyzer_run`, `get_analyzer_run_file`, `get_analyzer_run_response`, `get_analyzer_run_conversation`, `get_analyzer_run_insight`, `get_spend`, `get_brief_source`.

Each takes a single argument (e.g. `id` for the resource ID).

### List-by-parent tools

Return a list of resources for a given parent:

| Tool | Parent parameter |
|------|-------------------|
| `get_briefs_by_project` | `projectId` |
| `list_interviews_by_project` | `projectId` |
| `list_interview_guides_by_project` | `projectId` |
| `list_interview_sessions_by_interview` | `interviewId` |
| `list_interview_sessions_by_user` | `userId` |
| `list_interview_invitations_by_interview` | `interviewId` |
| `list_interview_invitations_by_user_token` | `userToken` |
| `list_discussion_guides_by_project` | `projectId` |
| `list_discussion_guides_by_brief` | `briefId` |
| `list_clients_by_organisation` | `organisationId` |
| `list_projects_by_organisation` | `organisationId` |
| `get_projects_by_client` | `clientId` |
| `list_organisation_members_by_organisation` | `organisationId` |
| `list_organisation_members_by_user` | `userId` |
| `list_organisation_invitations_by_organisation` | `organisationId` |
| `list_organisation_invitations_by_email` | `email` |
| `list_spend_by_project` | `projectId` |
| `list_analyzer_runs_by_project` | `projectId` |
| `list_analyzer_run_files_by_analyzer_run` | `analyzerRunId` |
| `list_analyzer_run_responses_by_analyzer_run` | `analyzerRunId` |
| `list_analyzer_run_conversations_by_analyzer_run` | `analyzerRunId` |
| `list_analyzer_run_insights_by_conversation` | `analyzerRunConversationId` |
| `list_brief_sources_by_brief` | `briefId` |

### Other list / search tools

| Tool | Description |
|------|-------------|
| `list_organisations` | GET all organisations (no parameters). |
| `list_interviews_open_to_all` | GET interviews that are open to all (no parameters). |
| `list_briefs` | List briefs with optional `userId`, `limit`, `offset`, `sortBy`, `sortOrder`. |
| `search_projects_by_organisation_and_client` | POST search: `organisationIds` (required), optional `clientId`, `tag`, `limit`, `offset`, `orderBy`, `orderDirection`. |

### Create / update / delete tools

Each domain entity has dedicated tools:

- **Organisation**: `create_organisation`, `update_organisation`, `delete_organisation`
- **Organisation member**: `create_organisation_member`, `update_organisation_member`, `delete_organisation_member`
- **Organisation invitation**: `create_organisation_invitation`, `update_organisation_invitation`, `delete_organisation_invitation`
- **Client**: `create_client`, `update_client`, `delete_client`
- **Project**: `create_project`, `update_project`, `delete_project`
- **Brief**: `create_brief`, `update_brief`, `delete_brief`
- **Brief source**: `create_brief_source`, `update_brief_source`, `delete_brief_source`
- **Spend**: `create_spend`, `update_spend`, `delete_spend`
- **Discussion guide**: `create_discussion_guide`, `update_discussion_guide`, `delete_discussion_guide`
- **Interview guide**: `create_interview_guide`, `update_interview_guide`, `delete_interview_guide`
- **Interview**: `create_interview`, `update_interview`, `delete_interview`
- **Interview session**: `create_interview_session`, `update_interview_session`, `delete_interview_session`
- **Interview invitation**: `create_interview_invitation`, `update_interview_invitation`, `delete_interview_invitation`
- **Analyzer run**: `create_analyzer_run`, `update_analyzer_run`, `delete_analyzer_run`
- **Analyzer run file**: `create_analyzer_run_file`, `update_analyzer_run_file`, `delete_analyzer_run_file` (use `isSpss` as string `"true"` or `"false"`)
- **Analyzer run response**: `create_analyzer_run_response`, `update_analyzer_run_response`, `delete_analyzer_run_response`
- **Analyzer run conversation**: `create_analyzer_run_conversation`, `update_analyzer_run_conversation`, `delete_analyzer_run_conversation`
- **Analyzer run insight**: `create_analyzer_run_insight`, `update_analyzer_run_insight`, `delete_analyzer_run_insight`

Each create/update tool takes a schema matching the API body (see server instructions or API docs for required and optional fields).

## Local development with npx

```bash
npm run build
npm link
npx @insightology.ai/imra-data-service-mcp http://localhost:3000
```

## Publishing

```bash
npm login
npm publish --access public
```

## License

Apache-2.0