@vstack/mcp-simpleone

MCP server for SimpleOne Table API. Allows AI assistants in Cursor to search, read, create and update records in any SimpleOne instance.

Quick Start

1. Get a Bearer Token

curl -s -X POST https://YOUR_INSTANCE/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"your-login","password":"your-password"}' \
  | jq -r .data.auth_key

Copy the returned token string.

2. Add to Cursor

Add to your .cursor/mcp.json:

{
  "mcpServers": {
    "simpleone": {
      "command": "npx",
      "args": ["-y", "@vstack/mcp-simpleone"],
      "env": {
        "SIMPLEONE_URL": "https://your-instance.simpleone.ru",
        "SIMPLEONE_TOKEN": "paste-your-token-here"
      },
      "autoApprove": ["simpleone_search", "simpleone_get"]
    }
  }
}

Reload Cursor window (Cmd+Shift+P > "Developer: Reload Window") and the server will appear in Settings > Tools & MCP.

Authentication

Two modes are supported. Token takes priority if both are set.

Bearer Token (recommended):

"env": {
  "SIMPLEONE_URL": "https://your-instance.simpleone.ru",
  "SIMPLEONE_TOKEN": "your-bearer-token"
}

Basic Auth (login + password):

"env": {
  "SIMPLEONE_URL": "https://your-instance.simpleone.ru",
  "SIMPLEONE_LOGIN": "your-login",
  "SIMPLEONE_PASSWORD": "your-password"
}

Tools

Read-only (safe to autoApprove)

| Tool | Description | |------|-------------| | simpleone_search | Search records in any table with query filter | | simpleone_get | Get a single record by sys_id |

Write (require user confirmation)

| Tool | Description | |------|-------------| | simpleone_create | Create a new record (POST) | | simpleone_update | Update an existing record (PATCH) |

Examples

Once connected, you can ask Cursor:

• "Show my features in backlog" — uses simpleone_search on pda_feature
• "What tasks are in sprint 5?" — searches pda_task by pda_sprint_id
• "Create a task for BE-1 under FTR0000514" — uses simpleone_create on pda_task (will ask for confirmation)
• "Update FTR0000514 state to analysis" — uses simpleone_update (will ask for confirmation)

Supported Tables

Works with any SimpleOne table accessible via /rest/v1/table/. Common ones:

| Table | Content | |-------|---------| | pda_feature | SDLC Features | | pda_task | SDLC Tasks | | pda_epic | Epics | | pda_sprint | Sprints | | pda_defect | Defects | | task | Base task table |

Security

• Credentials are passed via env block in mcp.json and never leave your machine
• The mcp.json file is local to your workspace — do not commit it to git if it contains secrets
• Write operations (create, update) always require explicit user approval in Cursor UI
• No data is sent anywhere except your SimpleOne instance

Publishing to npm

# Login to npm (one time)
npm login

# Build and publish
cd scripts/mcp-simpleone
npm run build
npm publish --access public

After publishing, anyone can use it:

npx -y @vstack/mcp-simpleone

Development

# Install dependencies
npm install

# Build
npm run build

# Test locally (set env vars first)
export SIMPLEONE_URL=https://your-instance.simpleone.ru
export SIMPLEONE_LOGIN=your-login
export SIMPLEONE_PASSWORD=your-password

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | node dist/index.js

Requirements

• Node.js >= 18.0.0
• SimpleOne instance with Table API access

License

MIT