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.

Prerequisites: Node.js 18+, npm, SmartSuite API credentials
Installation: npm install
Build: npm run build
Configuration: Set environment variables SMARTSUITE_API_TOKEN and SMARTSUITE_WORKSPACE_ID
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

Prerequisites

Node.js v18.x or higher
npm

Running Locally

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

Building for Production

Compile TypeScript: npm run build
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:

Copy example mappings from config/field-mappings/examples/
Remove from filenames
Place in config/field-mappings/ directory
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

This server cannot be installed

-

security - not tested

F

license - not found

-

quality - not tested

How are these scores calculated?

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

Enables interaction with SmartSuite workspace data through natural language, providing 6 tools for querying, managing records, exploring schemas, and performing operations with human-readable field names across 10+ configured table types including projects, tasks, clients, and schedules.

SmartSuite MCP Server