Skip to content

README.md

Latest commit

 

History

History
178 lines (129 loc) · 7.91 KB

README.md

File metadata and controls

178 lines (129 loc) · 7.91 KB
Raw

Teamwork MCP STDIO Server

STDIO transport server for the Teamwork Model Context Protocol implementation

Go MCP

📖 Overview

The Teamwork MCP STDIO Server provides a STDIO (Standard Input/Output) interface for the Model Context Protocol, enabling direct communication between Large Language Models and Teamwork.com through standard input and output streams. This server implements the MCP specification over STDIO transport, making it ideal for desktop applications and development environments.

🤖 What is the STDIO Server for?

This STDIO server is designed for:

  • Desktop LLM applications: Direct integration with local AI applications
  • Development and testing: Easy local development with MCP tools
  • Single-user environments: Efficient communication without network overhead
  • CLI tools and scripts: Integration with command-line workflows

✨ Features

  • STDIO Transport: Direct communication through standard input/output streams
  • Tool Framework: Extensible toolset architecture supporting all Teamwork operations
  • Read-Only Mode: Optional restriction to read-only operations for safety
  • Selective Toolsets: Enable specific toolsets or operations as needed
  • Secure Authentication: Bearer token-based authentication with Teamwork

🚀 Quick Start

📋 Prerequisites

  • Go 1.27 or later
  • Valid Teamwork API bearer token

🏃 Running the Server

# Basic STDIO server with all toolsets
TW_MCP_BEARER_TOKEN=your-bearer-token \
  go run cmd/mcp-stdio/main.go

# Read-only mode (safer for testing)
TW_MCP_BEARER_TOKEN=your-bearer-token \
  go run cmd/mcp-stdio/main.go -read-only

# PM profile: projects, tasks, people, and content only
TW_MCP_BEARER_TOKEN=your-bearer-token \
  go run cmd/mcp-stdio/main.go -toolsets=project-manager

# Support profile: Desk tickets and customers only
TW_MCP_BEARER_TOKEN=your-bearer-token \
  go run cmd/mcp-stdio/main.go -toolsets=support

# Read-only analyst: all toolsets but no writes
TW_MCP_BEARER_TOKEN=your-bearer-token \
  go run cmd/mcp-stdio/main.go -toolsets=analyst -read-only

# Specific sub-toolsets only
TW_MCP_BEARER_TOKEN=your-bearer-token \
  go run cmd/mcp-stdio/main.go -toolsets=twprojects-tasks,twprojects-content

⚙️ Configuration

Command-Line Flags

Flag Description Default Example
-toolsets Comma-separated list of sub-toolsets or profile names to enable all project-manager, twprojects-tasks,twdesk-tickets
-read-only Restrict the server to read-only operations false -read-only
Available profiles
Profile Toolsets included Intended use
project-manager twprojects-projects, twprojects-tasks, twprojects-people, twprojects-planning, twprojects-content Project managers working in Teamwork Projects
support (alias: desk) twdesk-tickets, twdesk-customers Support agents working in Teamwork Desk
analyst All sub-toolsets (combine with -read-only) Read-only reporting across both products
ops All sub-toolsets Full access — same as all
Available sub-toolsets
Sub-toolset Covers
twprojects-projects Projects, categories, templates, project members, industries
twprojects-tasks Tasks and tasklists
twprojects-people Users, companies, teams, skills, job roles
twprojects-planning Scheduler allocations, workload
twprojects-time Timelogs, timers, budgets
twprojects-content Comments, notebooks, milestones, tags, activities
twdesk-tickets Tickets, messages, files, inboxes
twdesk-customers Companies, customers, users
twdesk-admin Priorities, statuses, types, tags

Environment Variables

The server can be configured using the following environment variables:

Authentication Variables
Variable Description Example
TW_MCP_BEARER_TOKEN Bearer token for Teamwork API (required) your-bearer-token
Server Configuration
Variable Description Default Example
TW_MCP_VERSION Version of the MCP server dev v1.0.0
TW_MCP_API_URL The Teamwork API base URL https://teamwork.com https://example.teamwork.com
TW_MCP_RESTRICTED_INSTALLATION_IDS Installations whose tool results carry no personal data (contact details, avatars, timezones, cost rates, recipients); comma-separated (empty) 777,12345
Logging Configuration
Variable Description Default Example
TW_MCP_LOG_FORMAT Log output format text json, text
TW_MCP_LOG_LEVEL Logging level info debug, warn, error, fatal

📝 Usage Examples

Basic Usage

# Enable all toolsets (default)
TW_MCP_BEARER_TOKEN=your-token go run cmd/mcp-stdio/main.go

# Read-only mode for safety
TW_MCP_BEARER_TOKEN=your-token go run cmd/mcp-stdio/main.go -read-only

# project-manager profile: projects, tasks, people, and content
TW_MCP_BEARER_TOKEN=your-token go run cmd/mcp-stdio/main.go -toolsets=project-manager

# Support profile: Desk tickets and customers (also accepts -toolsets=desk)
TW_MCP_BEARER_TOKEN=your-token go run cmd/mcp-stdio/main.go -toolsets=support

# Combine sub-toolsets across products
TW_MCP_BEARER_TOKEN=your-token go run cmd/mcp-stdio/main.go \
  -toolsets=twprojects-tasks,twdesk-tickets

Integration with MCP Clients

The STDIO server can be integrated with any MCP-compatible client:

{
  "mcpServers": {
    "teamwork": {
      "command": "go",
      "args": ["run", "/path/to/teamwork/mcp/cmd/mcp-stdio/main.go"],
      "env": {
        "TW_MCP_BEARER_TOKEN": "your-bearer-token"
      }
    }
  }
}

🧪 Testing

MCP Inspector

For debugging purposes, use the MCP Inspector tool:

NODE_EXTRA_CA_CERTS=letsencrypt-stg-root-x1.pem npx @modelcontextprotocol/inspector node build/index.js

Important

Note: The NODE_EXTRA_CA_CERTS environment variable is required when using OAuth2 authentication with the Let's Encrypt certification authority. Download the certificate here.