ContentStudio MCP (Node + TypeScript)

A Node.js MCP server that mirrors your Laravel MCP tools and calls your existing API over HTTP with X-API-Key.

Default API base: https://api-prod.contentstudio.io (override with CONTENTSTUDIO_BASE_URL).

Tools

• ping
• validate_token
• fetch_workspaces
• fetch_social_accounts
• fetch_posts
• create_post
• delete_post
• help

Tool calls – auth_key is now mandatory

{
  "tool": "fetch_workspaces",
  "params": {
    "auth_key": "sk-XXXXXXXXXXXXXXXXXXXXXXXX",
    "page": 1,
    "per_page": 50
  }
}

• auth_key – your ContentStudio API key (X-API-Key header). Required for every tool call.
• base_url – optional override (defaults to CONTENTSTUDIO_BASE_URL env or https://api-prod.contentstudio.io).

Never store a global key on the server. The server only forwards the key you send.

Quick Start

1. Copy .env.example to .env (optional) and set:
   • CONTENTSTUDIO_BASE_URL (default https://api-prod.contentstudio.io if not set)
2. Install deps: npm install
3. Dev (stdio): npm run dev
4. Build & start: npm run build && npm start

Global usage (recommended)

After publishing to npm (see below), users can install or invoke the server globally:

• Global install:

  • npm i -g contentstudio-mcp
  • Then, in your MCP client config, use:

    {
      "mcpServers": {
        "contentstudio-node": {
          "command": "contentstudio-mcp"
        }
      }
    }

• Or with npx (no global install):

  • command: "bash"
  • args: ["-lc", "npx -y contentstudio-mcp"]

Windsurf MCP config

{ "mcpServers": { "contentstudio-node": { "command": "bash", "args": ["-lc", "cd /var/www/html/contentstudio-mcp && node --loader ts-node/esm src/index.ts"] } } }

Prod alternative (compiled JS): { "mcpServers": { "contentstudio-node": { "command": "bash", "args": ["-lc", "cd /var/www/html/contentstudio-mcp && node dist/index.js"] } } }

API Mapping

• validate_token → GET /api/v1/me
• fetch_workspaces → GET /api/v1/workspaces?page=&per_page=
• fetch_social_accounts → GET /api/v1/workspaces/{workspace_id}/accounts?platform=&page=&per_page=
• fetch_posts → GET /api/v1/workspaces/{workspace_id}/posts (date_from/date_to/status[] supported)
• create_post → POST /api/v1/workspaces/{workspace_id}/posts
• delete_post → DELETE /api/v1/workspaces/{workspace_id}/posts/{post_id}

Testing

This project includes a comprehensive test suite to verify the auth_key implementation and overall functionality.

Test Structure

tests/
├── unit/                    # Unit tests for individual components
│   └── api-client.test.js  # Tests for the apiRequest helper
├── integration/             # Integration tests for full tool workflows
│   ├── auth.test.js        # Tests auth_key requirements
│   ├── base-url.test.js    # Tests base_url override functionality
│   └── error-handling.test.js # Tests error scenarios
├── helpers/                 # Test utilities and helpers
│   └── test-utils.js       # Common test functions
└── setup.js                 # Global test configuration

Running Tests

# Run all tests
npm test

# Run quick tests (core functionality only)
npm run test:quick

# Run specific test categories
npm run test:unit                 # Unit tests only
npm run test:integration          # Integration tests only
npm run test:auth                 # Auth key tests
npm run test:base-url            # Base URL override tests
npm run test:error-handling      # Error handling tests
npm run test:simple              # Simple direct test

Test Coverage

The test suite covers:

• Auth Key Validation: Verifies all tools require auth_key and handle missing keys appropriately
• API Client: Unit tests for the apiRequest helper function including URL handling, headers, and error scenarios
• Base URL Override: Tests various URL formats, trailing slashes, ports, and protocols
• Error Handling: Invalid JSON, missing parameters, malformed requests, and edge cases
• Integration: End-to-end testing of the MCP server communication

Writing New Tests

When adding new tools or features:

1. Add unit tests in tests/unit/ for individual functions
2. Add integration tests in tests/integration/ for full tool workflows
3. Use the helper functions in tests/helpers/test-utils.js
4. Follow the existing test patterns and naming conventions

Test Configuration

Tests are configured in tests/setup.js with:

• Mock data and sample parameters
• Tool requirement definitions
• Error message expectations
• Global test settings

GitHub Actions

This project includes automated testing workflows:

Workflows

1. Full Test Suite (.github/workflows/tests.yml)

   • Runs on all Node.js versions (18.x, 20.x)
   • Executes all test categories
   • Includes build verification
   • Runs on pushes and PRs to main/master/develop

2. CI Pipeline (.github/workflows/ci.yml)

   • Quick build and test verification
   • Ensures no uncommitted changes after build
   • Runs on main/master branches

3. Quick Test (.github/workflows/quick-test.yml)

   • Fast feedback on core functionality
   • Runs quick tests and unit tests only
   • Ideal for frequent PR validation

Workflow Status

Local Testing Before Push

# Run the same tests as GitHub Actions
npm test

# Quick test (same as quick-test workflow)
npm run test:quick

# Build verification (same as CI workflow)
npm run build

Notes

• auth_key is required for every tool call – provide it in the tool parameters.
• base_url can be overridden per-call or via CONTENTSTUDIO_BASE_URL environment variable (default: https://api-prod.contentstudio.io).
• create_post: publish_type supports scheduled or draft. Use scheduled_at with scheduled, and you may also include scheduled_at with draft.
• create_post: video must be a direct URL string (e.g., https://...).