ProjectSight MCP Server

ProjectSight MCP Server

A scalable, maintainable MCP (Model Context Protocol) server that provides access to the ProjectSight API for managing portfolios, projects, and various record types like ActionItems, RFIs, Submittals, and more.

This server has been refactored into a modular, teachable structure that demonstrates best practices for building MCP servers. It's designed to be both production-ready and an excellent learning resource.

🎯 Features

• OAuth2 Authentication: Automatic token management with caching and refresh
• Modular Architecture: Clean separation of concerns, easy to extend
• Project Operations: Access project information
• Record Management: CRUD operations for:
  • ActionItems
  • RFIs (Request for Information)
  • Submittals
• Workflow States: Get workflow states for record types
• Debug Tools: Test connection, debug tokens, test different scopes

📁 Project Structure

projectsight-mcp/
├── mcp/                       # Main MCP server code
│   ├── main.py               # Entry point - run this to start the server
│   ├── config.py             # Configuration management
│   ├── auth.py               # OAuth2 authentication
│   ├── client.py             # API client for HTTP requests
│   ├── utils.py              # Utility functions
│   └── tools/                # MCP tools organized by domain
│       ├── __init__.py       # Tool registration
│       ├── debug.py          # Debug/diagnostic tools
│       ├── projects.py       # Project operations
│       ├── action_items.py   # Action item CRUD
│       ├── rfis.py           # RFI operations
│       ├── submittals.py     # Submittal operations
│       └── workflow.py       # Workflow state tools
├── README.md                 # This file
└── .env                      # Environment variables (create this)

🚀 Quick Start

1. Install Dependencies

pip install fastmcp python-dotenv aiohttp uvicorn

Or using a virtual environment:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install fastmcp python-dotenv aiohttp uvicorn

2. Configure Credentials

Create a .env file in the mcp/ directory (or project root) with your ProjectSight API credentials:

APPLICATION_NAME=your_app_name
CLIENT_ID=your_client_id
CLIENT_SECRET=your_client_secret
PORTFOLIO_ID=your_portfolio_id_or_guid
PROJECTSIGHT_API_URL=https://cloud.api.trimble.com/projectsight/us1/1.0
PROJECTSIGHT_SCOPE=ProjectSight_-_US1

Getting Credentials:

1. Sign in to API Cloud with your Trimble account
2. On the Discover API page, select ProjectSight or ProjectSight-EU
3. Select Subscriptions and subscribe your application
4. Select Get Key and copy:
   • Application Name
   • Consumer Key (CLIENT_ID)
   • Consumer Secret (CLIENT_SECRET)

For more information, email ProjectSightAPISupport@trimble.com to request API access.

Note on Scope: The PROJECTSIGHT_SCOPE should match your API subscription region:

• ProjectSight_-_US1 for US region
• ProjectSight_-_EU1 for EU region
• ProjectSight_-_US2 for Azure US region

3. Run the Server

STDIO Mode (default for MCP clients):

cd mcp
python main.py

HTTP Streaming Mode:

cd mcp
python main.py --http

With custom host/port:

# Windows PowerShell
$env:MCP_HOST="0.0.0.0"
$env:MCP_PORT="8000"
python main.py --http

# Linux/Mac
export MCP_HOST=0.0.0.0
export MCP_PORT=8000
python main.py --http

🔧 MCP Client Configuration

STDIO Mode (Cursor, Claude Desktop, etc.)

{
    "mcpServers": {
        "projectsight": {
            "command": "python",
            "args": ["C:\\Users\\cforey\\Desktop\\projectsight-mcp\\mcp\\main.py"],
            "env": {
                "APPLICATION_NAME": "your_app_name",
                "CLIENT_ID": "your_client_id",
                "CLIENT_SECRET": "your_client_secret",
                "PORTFOLIO_ID": "your-portfolio-guid-or-account-id"
            }
        }
    }
}

Note: You can also use a .env file instead of setting environment variables in the config. The script will automatically load variables from a .env file in the mcp/ directory.

HTTP Mode

For MCP clients that support HTTP transport, configure the connection URL:

http://localhost:8000/mcp

📚 Available Tools

Connection & Debug Tools

• test_connection(): Test the connection to ProjectSight API and verify authentication
• debug_token(): Debug token acquisition and validation (without exposing the actual token)
• test_different_scopes(): Test different scope combinations to find what works

Project Operations

• get_projects(portfolio_guid): Get Projects for a specific Portfolio. If portfolio_guid is not provided, uses PORTFOLIO_ID from .env.

ActionItem Operations

• get_action_item(portfolio_guid, project_id, action_item_id): Get an indi