Voting Services MCP

Model Context Protocol server for the multi-tenant voting services API, enabling AI assistants to manage democratic community governance.

Setup

Install Dependencies

bun install

Environment Configuration

Create a .env file with the following variables:

# Required: Bearer token for authentication with the voting services API
MCP_SERVICE_SECRET=your-bearer-token-here

# Optional: Base URL for the voting services API (defaults to localhost:3000)
VOTING_API_BASE_URL=http://localhost:3000/api/v1

Run Development Server

Stdio Mode (default):

bun run dev

HTTP Mode:

bun run dev:http

Build for Production

bun run build

Run in Stdio Mode:

bun run start

Run in HTTP Mode:

bun run start:http

Server Modes

Stdio Mode (default):

• Uses stdin/stdout for communication
• Ideal for CLI integration and MCP clients
• Default port: N/A (stdio transport)

HTTP Mode:

• RESTful HTTP server with StreamableHTTP transport
• Supports session management and concurrent connections
• Default port: 3001 (configurable via PORT environment variable)
• Health check endpoint: http://localhost:3001/health
• MCP endpoint: http://localhost:3001/mcp

Features

This MCP server provides AI assistants with tools to:

• 🏗️ Create Community Groups - Set up democratic voting communities
• 📝 Submit Member Proposals - Propose adding or removing members
• 🗳️ Cast Votes - Vote on membership proposals with reasoning
• 📊 Monitor Group Activity - Track participation and engagement
• ✅ Verify Member Eligibility - Check membership criteria compliance

Architecture

Built following the hats-mcp-server pattern with:

• Operations-based structure for individual MCP tools
• Zod validation for type safety and input validation
• Multi-tenant support with group-scoped operations
• Natural language examples for user-friendly interactions

This project was created using bun init in bun v1.2.15. Bun is a fast all-in-one JavaScript runtime.