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

A

license - permissive license

-

quality - not tested

How are these scores calculated?

Resources

GitHub Repository

Need Help?

Report Issue

Related Servers

SmartSuite MCP Server