@voteship/mcp-server

MCP (Model Context Protocol) server for VoteShip — manage feature requests, votes, roadmaps, and AI workflows from any MCP-compatible client.

Works without an API key — public tools let any agent submit feedback, browse boards, vote, and comment.

Remote Streamable HTTP

Connect a hosted MCP client to https://voteship.app/mcp. Public tools and the agent-guide resource require no credentials. For project administration, attach your VoteShip secret as Authorization: Bearer sk_... only when the client can store it securely.

Connect in one command

Claude Code

Public tools, resources, prompts, and the interactive board work without an API key:

claude mcp add --transport http --scope user voteship https://voteship.app/mcp

Codex

codex mcp add voteship --url https://voteship.app/mcp

Verify the connection with claude mcp get voteship or codex mcp get voteship.

Authenticated project administration

Keep the secret in the MCP host environment and run the local package. Claude Code:

claude mcp add --scope user --env VOTESHIP_API_KEY=sk_... voteship -- npx -y @voteship/mcp-server

Codex:

codex mcp add voteship --env VOTESHIP_API_KEY=sk_... -- npx -y @voteship/mcp-server

For a shared project configuration, keep the key out of source control and use your client's environment-variable support:

{
  "mcpServers": {
    "voteship": {
      "command": "npx",
      "args": ["-y", "@voteship/mcp-server"],
      "env": {
        "VOTESHIP_API_KEY": "${VOTESHIP_API_KEY}"
      }
    }
  }
}

Find the secret key in VoteShip → Share & Embed. Never put an sk_ key in client-side code or commit it to a repository.

Install VoteShip on a website

npx -y @voteship/cli init --project-key pk_your_public_key
npx -y @voteship/cli verify --url https://your-site.example

The installer detects common Next.js, React, Vue, Vite, SvelteKit, Angular, and plain HTML entry files. See the complete VoteShip installation guide.

Public Tools (4) — No API Key Required

| Tool | Description | |------|-------------| | submit_feature_request | Submit feedback to any public VoteShip board. Post created as PENDING (requires board owner approval). | | browse_board | View approved feature requests on a public board, sorted by votes | | upvote_post | Vote/unvote on a feature request (uses deterministic anonymous ID) | | add_public_comment | Add a comment to a feature request |

Admin Tools (30) — Requires API Key

| Tool | Description | |------|-------------| | list_posts | List feature requests with optional filters | | get_post | Get a single post with votes, comments, tags | | create_post | Create a new feature request | | update_post | Update a post's title, description, status, or tags | | delete_post | Delete a feature request | | search_similar | Find similar posts using AI semantic search | | add_vote | Vote on a feature request | | get_voters | List who voted on a post | | add_comment | Add a comment to a post | | get_comments | List comments on a post | | delete_comment | Delete a comment from a post | | list_tags | List all available tags | | create_tag | Create a new tag | | list_users | List board users | | update_user | Update a board user's name, email, or spend value | | get_roadmap | Get the product roadmap grouped by status | | get_analytics | Get analytics summary for a time period | | list_releases | List published changelog releases | | create_release | Create a changelog release | | submit_feedback | Submit unstructured text as a feature request (AI processes it) | | triage_inbox | AI-powered triage of unreviewed posts | | get_summary | AI-generated summary of recent feedback | | plan_sprint | AI-suggested sprint based on votes and themes |

Resources (7)

| URI | Description | |-----|-------------| | voteship://service/agent-guide | Credential-free public-mode setup, safety, and documentation guide | | ui://voteship/board.html | Read-only MCP App UI rendered by browse_board in compatible hosts | | voteship://project/overview | Project info and summary stats | | voteship://project/board | Full board state with all posts | | voteship://project/roadmap | Public roadmap view | | voteship://project/changelog | Published releases | | voteship://project/analytics | Analytics snapshot |

Prompts (5)

| Name | Description | |------|-------------| | triage_inbox | Review and categorize unprocessed feature requests | | sprint_planning | Suggest what to build next based on data | | generate_changelog | Draft release notes from recently completed posts | | feedback_summary | Summarize feedback trends and highlights | | submit_feedback | Guide for submitting a well-structured feature request (works in public mode) |

Example Usage

Public mode (any agent):

> Submit a feature request to the acme-app board: "Add dark mode support"

Admin mode (with API key):

> Triage my VoteShip inbox and suggest what to build this sprint

The agent will:

1. Fetch unreviewed posts and analyze them
2. Flag duplicates and suggest statuses
3. Recommend a sprint plan based on votes and themes
4. Generate changelog drafts for completed features

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | VOTESHIP_API_KEY | No | API secret key (sk_...) for full admin access. Omit for public-only mode. | | VOTESHIP_PROJECT_SLUG | No | Default project slug for public tools (e.g. my-app) | | VOTESHIP_API_URL | No | Custom API URL (default: https://app.voteship.app) |

Development

Testing

# Run tests
pnpm test

# Run with coverage
pnpm test:coverage

The MCP server has 82 tests covering:

• Client HTTP layer — URL construction, headers, auth, error handling for all 25+ methods
• Server registration — All 34 tools, 7 resources, 5 prompts verified
• Tool callbacks — Success/error paths, public tool slug resolution
• Resource callbacks — Data formatting and response structure

Coverage thresholds are enforced: 55% lines, 40% branches, 70% functions, 55% statements.

License

MIT