SmartSuite API Shim

Status: ✅ Functional - B4+ Working Implementation
Test Coverage: 348+ tests passing with recent MongoDB filtering and schema optimization fixes
Server Status: Fully functional with auto-authentication, 6 MCP tools, and latest enhancements

Quick Start

⚠️ IMPORTANT: Read docs/001-ARCHITECTURE.md before making changes to understand system constraints and common failure modes.

1. Prerequisites: Node.js 18+, npm, SmartSuite API credentials
2. Installation: npm install
3. Build: npm run build
4. Configuration: Set environment variables SMARTSUITE_API_TOKEN and SMARTSUITE_WORKSPACE_ID
5. Usage: npm start - MCP server with 6 SmartSuite tools ready

Features

🎯 Completed B4+ Achievements:

• ✅ Auto-Authentication - Environment variable authentication with fail-fast pattern
• ✅ Field Translation - Human-readable field names for 10 SmartSuite tables
• ✅ 6 SmartSuite Tools - query, record, schema, undo, discover, intelligent operations
• ✅ DRY-RUN Safety - Mutation protection with explicit confirmation required
• ✅ Comprehensive Testing - 348+ tests with recent MongoDB filtering and schema optimization fixes
• ✅ CI/CD Pipeline - Fully resolved with CodeQL integration and quality gates
• ✅ Error Handling - Graceful degradation and clear error messages
• ✅ Production Validation - All critical API fixes applied and verified
• ✅ Enhanced Code Quality - Nullish coalescing, console cleanup, path resolution fixes

Available Tools

Tool	Description	Status
smartsuite_query	List, search, get records with MongoDB-style filtering support	✅ Ready
smartsuite_record	Create, update, delete records with DRY-RUN safety	✅ Ready
smartsuite_schema	Get table schema with 3 output modes (summary/fields/detailed) + caching	✅ Ready
smartsuite_undo	Transaction rollback operations	✅ Ready
smartsuite_discover	Field mapping discovery and table structure exploration	✅ Ready
smartsuite_intelligent	AI-guided API operations with knowledge-driven safety	✅ Ready

Supported Tables (10 Configured with Example Mappings)

• Projects (47 mapped fields) - Core project management
• Tasks (26 mapped fields) - Task tracking and assignments
• Videos (21 mapped fields) - Video production workflow
• Clients (21 mapped fields) - Client relationship management
• Schedule (24 mapped fields) - Calendar and timeline management
• Planning (25 mapped fields) - Resource planning and phase management
• Financial Records - Cost tracking and invoicing
• Services - Service catalog and offerings
• Content Items - Content asset management
• Issue Log (26 mapped fields) - Problem tracking and resolution

Note: Field mappings are workspace-specific. Copy examples from config/field-mappings/examples/ to create your own mappings.

Development

This is a TypeScript project. The source code is located in the /src directory. It is compiled into JavaScript in the /build directory for execution. Do not edit files in /build directly, as they will be overwritten.

Prerequisites

• Node.js v18.x or higher
• npm

Running Locally

1. Install dependencies: npm install
2. Run in development mode (with auto-reload): npm run dev

Building for Production

1. Compile TypeScript: npm run build
2. Run the compiled code: npm start

Testing

• Run all tests: npm test
• Run tests with coverage: npm run test:coverage
• Watch mode: npm run test:watch

Project Structure

• src/ - TypeScript source code
• build/ - Compiled JavaScript (generated, do not edit)
• test/ - Test suites
• docs/ - Documentation
• reports/ - Build phase reports

Configuration & Usage

Field Mappings Setup

Since field mappings are workspace-specific and not included in the repository:

1. Copy example mappings from config/field-mappings/examples/
2. Remove .example suffix from filenames
3. Place in config/field-mappings/ directory
4. Customize field mappings for your SmartSuite workspace

The system automatically loads all .yaml files from config/field-mappings/ on startup.

Environment Variables (Required for Auto-Authentication)

# Set these for automatic authentication on server startup
export SMARTSUITE_API_TOKEN="your-smartsuite-api-key"
export SMARTSUITE_WORKSPACE_ID="your-workspace-id" 

Production Deployment

# Compile and run
npm run build
npm start

# Validation mode (for CI/CD)
MCP_VALIDATE_AND_EXIT=true npm start

Integration with Claude Desktop

Add to your Claude Desktop MCP configuration:

{
  "mcpServers": {
    "smartsuite": {
      "command": "node",
      "args": ["/path/to/smartsuite-api-shim/build/src/index.js"],
      "env": {
        "SMARTSUITE_API_TOKEN": "your-api-token",
        "SMARTSUITE_WORKSPACE_ID": "your-workspace-id"
      }
    }
  }
}

Critical Documentation - READ FIRST

🚨 System Context (Required Reading)

• 🎯 NORTH STAR: docs/000-NORTH-STAR.md - Project vision and goals
• 🏗️ ARCHITECTURE: docs/001-ARCHITECTURE.md - System design, failure modes, what will break

User & Technical Guides

• Complete User Guide: docs/guides/001-DOC-GUIDE-USER-GUIDE.md - Detailed usage instructions with examples
• Technical Handoff: docs/delivery/202-PROJECT-SMARTSUITE-API-SHIM-B4-HANDOFF.md - Implementation details and architecture

Example Usage

// Query projects with human-readable field names
{
  "operation": "list",
  "appId": "68a8ff5237fde0bf797c05b3",
  "filters": {
    "projectName": "Website Redesign",  // Instead of "project_name_actual"
    "priority": "High",                 // Instead of cryptic priority codes
    "client": "client-abc-123"          // Instead of "sbfc98645c"
  }
}

Coordination Access

Access project management via .coord/ symlink