@brxce/bruce-studio-mcp

MCP (Model Context Protocol) server for Bruce Studio - Content management and marketing automation for Threads.

Features

• Content CRUD: Create, read, update, delete content metadata
• Revision Management: Full version control with branching support
• Insights: User editing pattern analysis
• Analytics: Performance metrics and analysis
• Threads Data: Threads posts/analytics 조회 및 동기화

Architecture

This MCP server connects Claude Desktop to the Bruce Studio API backend:

┌─────────────────┐      ┌─────────────────┐      ┌─────────────────┐
│  Claude Desktop │◄────►│   MCP Server    │◄────►│   API Server    │
│  (AI Assistant) │      │   (stdio)       │      │   (Port 9000)   │
└─────────────────┘      └─────────────────┘      └─────────────────┘

Setup

Prerequisites

• Node.js 18+
• Bruce Studio API server running on port 9000
• Claude Desktop application

Installation

No installation required - runs via npx.

Environment Variables

| Variable | Description | Required | |----------|-------------|----------| | BACKEND_URL | Bruce Studio API endpoint | Yes |

Claude Desktop Integration

Add this configuration to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "bruce-studio-mcp": {
      "command": "npx",
      "args": ["-y", "@brxce/bruce-studio-mcp"],
      "env": {
        "BACKEND_URL": "http://localhost:9000/api/v1"
      }
    }
  }
}

After updating the config, restart Claude Desktop.

Claude Code Integration

Add to your .mcp.json:

{
  "mcpServers": {
    "bruce-studio-mcp": {
      "command": "npx",
      "args": ["-y", "@brxce/bruce-studio-mcp"],
      "env": {
        "BACKEND_URL": "http://localhost:9000/api/v1"
      }
    }
  }
}

Available MCP Tools

Content Management

threads_list_contents

List all contents with optional filters

Parameters:

• category (optional): Filter by category/pillar
• status (optional): Filter by status (draft, approved, scheduled, published)
• limit (optional): Maximum number of results (default: 50)

Example:

{
  "category": "productivity-tips",
  "status": "published",
  "limit": 10
}

threads_get_content

Get a specific content by UUID (includes current revision text)

Parameters:

• contentId (required): Content UUID

threads_create_content

Create a new content with initial revision

Parameters:

• title (optional): Content title
• text (optional): Initial content text
• status (optional): Status (default: 'draft')
• category (optional): Content category/pillar
• tags (optional): Array of tags
• message (optional): Initial revision message

threads_update_content_metadata

Update content metadata (does NOT change text - use threads_create_revision to edit text)

Parameters:

• contentId (required): Content UUID
• title (optional): New title
• status (optional): New status
• category (optional): New category
• tags (optional): New tags
• scheduledDate (optional): Scheduled publish date (ISO 8601)
• publishedDate (optional): Published date (ISO 8601)
• liked (optional): Liked status
• impressions (optional): Number of impressions
• engagementRate (optional): Engagement rate (0-1)

threads_delete_content

Delete a content and all its revisions

Parameters:

• contentId (required): Content UUID to delete

threads_get_pillars

Get list of available content pillars/categories

Parameters: None

Revision Management

threads_list_revisions

List all revisions for a content (metadata only, no text)

Parameters:

• contentId (required): Content UUID

threads_get_revision

Get a specific revision by UUID (includes full text content)

Parameters:

• contentId (required): Content UUID
• revisionId (required): Revision UUID

threads_get_revision_tree

Get the full revision tree showing parent-child relationships (branching structure)

Parameters:

• contentId (required): Content UUID

Returns: Tree structure with all revisions and their relationships

threads_create_revision

Create a new revision (version) of content text

Parameters:

• contentId (required): Content UUID
• content (required): New revision text content
• message (optional): Commit message describing changes
• author (optional): 'manual' or 'ai' (default: 'manual')
• aiPrompt (optional): AI prompt used (if author='ai')
• parentRevisionId (optional): Parent revision UUID (defaults to current revision)
• setAsCurrent (optional): Set this revision as the current one (default: true)

Example - Creating a new revision:

{
  "contentId": "a894ed46-cad9-466f-95f1-42614a7e780a",
  "content": "Updated content text...",
  "message": "Fixed typos and improved clarity",
  "author": "manual"
}

Example - Creating a branch:

{
  "contentId": "a894ed46-cad9-466f-95f1-42614a7e780a",
  "content": "Alternative version...",
  "message": "Trying a different approach",
  "parentRevisionId": "2e4d48c3-06e6-4441-b21e-8d2110bdc1b9",
  "setAsCurrent": false
}

threads_update_revision_metadata

Update revision metadata (message, author, aiPrompt)

Parameters:

• contentId (required): Content UUID
• revisionId (required): Revision UUID
• message (optional): New commit message
• author (optional): Update author type
• aiPrompt (optional): Update AI prompt

threads_delete_revision

Delete a revision (optionally cascade to children)

Parameters:

• contentId (required): Content UUID
• revisionId (required): Revision UUID to delete
• cascade (optional): Also delete all child revisions (default: false)

threads_restore_revision

Restore an old revision by creating a new revision from it

Parameters:

• contentId (required): Content UUID
• revisionId (required): Revision UUID to restore from
• message (optional): Custom message (default: "Restored from revision {hash}")

Insights

threads_list_insights

List editing insights with optional scope filtering

Parameters:

• scope (optional): Filter by scope type ('user', 'content', 'pillar')
• contentId (optional): Filter by specific content
• pillar (optional): Filter by pillar

threads_get_insight

Get detailed information about a specific insight

Parameters:

• insightId (required): Insight ID

threads_get_insight_context

Get formatted insight context for LLM to understand user editing patterns

Parameters:

• scope (optional): Scope type
• contentId (optional): Content ID
• pillar (optional): Pillar name

Analytics

threads_analyze_performance

Analyze performance metrics across contents

Parameters:

• startDate (optional): Start date (ISO 8601)
• endDate (optional): End date (ISO 8601)
• pillar (optional): Filter by pillar

Threads Data

threads_read_posts

Fetch Threads posts from the local DB (optionally force sync with Threads API) and display summary + preview.

Parameters:

• sync (optional): Set to true to trigger a fresh sync before returning data

Response: Includes totals (posts/views/likes/replies/avg engagement), date range, optional sync metadata, and up to 5 preview posts with engagement data.

Development

Running in Development

npm run dev

Building

npm run build

Testing

# Test with a simple script
node test-api.js

Data Models

Content

Metadata container for a piece of content (does NOT contain text):

interface Content {
  id: string                  // UUID
  title: string
  status: 'draft' | 'approved' | 'scheduled' | 'published'
  category: string            // pillar (quicknote, productivity-tips, etc.)
  tags: string[]
  currentRevisionId: string   // UUID of active revision
  createdAt: string
  updatedAt: string
  scheduledDate?: string
  publishedDate?: string
  liked: boolean
  impressions: number
  engagementRate: number
}

ContentRevision

Versioned snapshot of content text:

interface ContentRevision {
  id: string                  // UUID
  contentId: string           // Parent content UUID
  revisionNumber: number      // Sequential number (1, 2, 3...)
  hash: string                // Git-style 7-character hash
  content: string             // The actual text content
  parentRevisionId: string | null  // Parent revision UUID (null for root)
  children: string[]          // Child revision UUIDs
  message: string             // Commit message
  author: 'manual' | 'ai'
  aiPrompt?: string
  createdAt: string
}

Troubleshooting

MCP Server Not Showing in Claude Desktop

1. Check that the path in claude_desktop_config.json is absolute and correct
2. Verify the API server is running on port 9000
3. Restart Claude Desktop completely
4. Check Claude Desktop logs for errors

Connection Errors

1. Ensure BACKEND_URL environment variable is set correctly
2. Verify the API server is accessible at the specified URL
3. Check for firewall or network issues

Tool Execution Errors

1. Check the API server logs for detailed error messages
2. Verify that content/revision IDs are valid UUIDs
3. Ensure required parameters are provided

Related Projects

• bruce-studio-api - Backend API server
• bruce-studio-web - Web frontend
• @brxce/shared - Shared TypeScript types and schemas

License

MIT