MathAI Feedback MCP Server

Model Context Protocol (MCP) server for MathAI Feedback System. Provides 8 tools for managing audio feedback assets in Claude Desktop.

Quick Start

No installation required! Claude Desktop will automatically download the package via npx.

1. Get your API credentials:

   • Get your authentication secret token from your MathAI dashboard
   • Default API URL: https://fk.c.mathai.ai (no configuration needed)
   • For local development, use http://localhost:3000

2. Configure Claude Desktop:

   Add to ~/Library/Application Support/Claude/claude_desktop_config.json (Mac) or equivalent:

   {
     "mcpServers": {
       "mathai-feedback": {
         "command": "npx",
         "args": ["-y", "@beingtmk/feedback-mcp"],
         "env": {
           "USER_SECRET": "your-secret-token"
         }
       }
     }
   }

   Note: API_BASE_URL defaults to https://fk.c.mathai.ai. Only override if using a different server:

   {
     "mcpServers": {
       "mathai-feedback": {
         "command": "npx",
         "args": ["-y", "@beingtmk/feedback-mcp"],
         "env": {
           "API_BASE_URL": "http://localhost:3000",
           "USER_SECRET": "your-secret-token"
         }
       }
     }
   }

3. Restart Claude Desktop (completely quit and reopen)

4. Test it:

   Search for encouragement feedback

Available Tools

1. search_feedback

Search for audio feedback assets by category, tags, or text query.

Example:

Search for encouragement feedback with the tag "correct"

2. create_feedback

Create new audio feedback with optional subtitle and sticker.

Example:

Create audio that says "Fantastic work!" in the encouragement category

3. update_feedback_subtitle

Add or update subtitle text for existing audio.

Example:

Update subtitle for feedback "audio_custom_123" to say "Great job!"

4. update_feedback_sticker

Add or update sticker animation for existing audio.

Example:

Add a star sticker to feedback "audio_custom_123"

5. update_feedback

Update core properties like name, category, description, and tags.

Example:

Add tag "motivational" to feedback "audio_custom_123"

6. delete_feedback

Delete a feedback asset.

Example:

Delete feedback "audio_custom_123"

7. get_categories

Get all available feedback categories.

Example:

Show me all feedback categories

8. generate_dynamic_audio

Generate audio at runtime with dynamic variable values.

Example:

Generate audio: "Great! You got {score} out of {total} correct"
with score=8 and total=10

Configuration

Environment Variables

Environment variables are provided via Claude Desktop config (NOT via .env file):

• API_BASE_URL (optional): Base URL of the API server

  • Default: https://fk.c.mathai.ai (production)
  • Local development: http://localhost:3000
  • Custom deployment: https://your-domain.com

• USER_SECRET (required): Authentication secret token

  • Get from your MathAI dashboard
  • Must match a secret in the API server's USERS configuration
  • IMPORTANT: Never commit this secret to git or share it publicly

Claude Desktop Config Locations

• Mac: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Development Setup

Running Locally

# Clone repository
git clone https://github.com/the-hw-app/claude-feedback-kit.git
cd claude-feedback-kit

# Install dependencies
npm install

# Build
npm run build

# Run API server
cd api
npm run dev

# Configure Claude Desktop to use local MCP server

Claude Desktop config for local development:

{
  "mcpServers": {
    "mathai-feedback": {
      "command": "node",
      "args": [
        "/absolute/path/to/claude-feedback-kit/mcp-server/dist/index.js"
      ],
      "env": {
        "API_BASE_URL": "http://localhost:3000",
        "USER_SECRET": "your-dev-secret"
      }
    }
  }
}

Updating

When using npx, the latest version is automatically downloaded each time Claude Desktop starts. To force a specific version, update your config:

{
  "mcpServers": {
    "mathai-feedback": {
      "command": "npx",
      "args": ["-y", "@beingtmk/[email protected]"],
      "env": {
        "USER_SECRET": "your-secret-token"
      }
    }
  }
}

Troubleshooting

Tools Not Appearing

1. Verify Claude Desktop config:

   cat ~/Library/Application\ Support/Claude/claude_desktop_config.json

2. Restart Claude Desktop completely (Cmd+Q, not just close window)

3. Check npx can access the package:

   npx -y @beingtmk/feedback-mcp --help

Connection Errors

1. Test API server:

   curl https://your-domain.com/health

2. Check authentication:

   curl -H "Authorization: Bearer your-secret" \
        https://your-domain.com/api/feedback/categories

3. Verify environment variables in Claude Desktop config

MCP Server Crashes

Check Claude Desktop logs:

~/Library/Logs/Claude/mcp*.log

Links

• GitHub: https://github.com/the-hw-app/claude-feedback-kit
• Documentation: Full setup guide in repository
• API Deployment: See DEPLOYMENT.md
• Issues: https://github.com/the-hw-app/claude-feedback-kit/issues

License

MIT