SmartSheet Dev MCP

A Model Context Protocol (MCP) server built with mcp-framework that provides tools for GitLab and Temporal workflow integration for development workflows.

Quick Start

# Install dependencies
npm install

# Build the project
npm run build

# Test locally
npm start

Project Structure

smartsheet-dev-mcp/
├── src/
│   ├── tools/           # MCP Tools
│   │   ├── GitlabReviewMrTool.ts
│   │   ├── GitlabExplainTraceTool.ts
│   │   ├── TemporalSearchTemporalWorkflowsTool.ts
│   │   └── TemporalSummarizeWorkflowTool.ts
│   ├── apis/            # API clients
│   │   ├── gitlab-api.ts
│   │   └── temporal-api.ts
│   ├── types/           # Type definitions
│   │   └── temporal-workflow.ts
│   └── index.ts         # Server entry point
├── package.json
├── tsconfig.json
└── release.sh           # Automated release script

Features

• GitLab Integration: Review merge requests, explain CI/CD traces
• Temporal Workflow Support: Search and summarize workflow executions
• MCP Framework: Built for seamless integration with Claude Desktop
• TypeScript: Fully typed for better development experience

Adding Components

The project comes with an example tool in src/tools/ExampleTool.ts. You can add more tools using the CLI:

# Add a new tool
mcp add tool my-tool

# Example tools you might create:
mcp add tool data-processor
mcp add tool api-client
mcp add tool file-handler

Tool Development

Example tool structure:

import { MCPTool } from "mcp-framework";
import { z } from "zod";

interface MyToolInput {
  message: string;
}

class MyTool extends MCPTool<MyToolInput> {
  name = "my_tool";
  description = "Describes what your tool does";

  schema = {
    message: {
      type: z.string(),
      description: "Description of this input parameter",
    },
  };

  async execute(input: MyToolInput) {
    // Your tool logic here
    return `Processed: ${input.message}`;
  }
}

export default MyTool;

Publishing New Versions

This project follows semantic versioning (SemVer). Use the appropriate version bump based on your changes:

• Patch (0.0.5 → 0.0.6): Bug fixes, minor improvements
• Minor (0.0.5 → 0.1.0): New features, backwards-compatible changes
• Major (0.0.5 → 1.0.0): Breaking changes

Quick Release (Recommended)

Use the automated release script for a streamlined workflow:

# Make the script executable (first time only)
chmod +x release.sh

# Release a patch version
./release.sh patch "fix: resolve authentication issue"

# Release a minor version  
./release.sh minor "feat: add new GitLab integration"

# Release a major version
./release.sh major "feat!: redesign API with breaking changes"

The script will:

1. ✅ Check git working directory status
2. ✅ Commit any uncommitted changes (with your permission)
3. ✅ Run validation (lint, build, test)
4. ✅ Bump the version in package.json
5. ✅ Create a git tag
6. ✅ Push changes and tags to remote

Manual Release Process

If you prefer manual control, use these npm scripts:

# 1. Check for uncommitted changes
npm run version:check

# 2. Commit any pending changes
git add .
git commit -m "your commit message"

# 3. Release (includes validation, version bump, and push)
npm run release:patch   # for patch version
npm run release:minor   # for minor version  
npm run release:major   # for major version

Version-Only (No Push)

To bump versions locally without automatic pushing:

npm run version:patch   # 0.0.5 → 0.0.6
npm run version:minor   # 0.0.5 → 0.1.0
npm run version:major   # 0.0.5 → 1.0.0

Development Scripts

# Validation (runs before every release)
npm run validate        # lint + build + test

# Individual checks
npm run lint           # ESLint code checking
npm run build          # TypeScript compilation
npm run test           # Jest test suite

Release Checklist

Before releasing:

• [ ] All tests pass (npm test)
• [ ] Code is properly linted (npm run lint)
• [ ] Build succeeds (npm run build)
• [ ] Changes are documented
• [ ] Version type matches change impact (patch/minor/major)

Troubleshooting Releases

"Git working directory not clean" error:

# Check what files have changes
git status

# Commit or stash changes
git add . && git commit -m "prepare for release"
# OR
git stash

Build or test failures:

# Run validation to see specific issues
npm run validate

# Fix issues, then try release again
./release.sh patch "fix: resolve build issues"

Push failures:

# Check remote connection
git remote -v

# Manual push if needed
git push origin main --follow-tags

Publishing to npm

1. Update your package.json:

   • Ensure name is unique and follows npm naming conventions
   • Set appropriate version
   • Add description, author, license, etc.
   • Check bin points to the correct entry file

2. Build and test locally:

   npm run build
   npm link
   gitlab  # Test your CLI locally

3. Login to npm (create account if necessary):

   npm login

4. Publish your package:

   npm publish

After publishing, users can add it to their claude desktop client (read below) or run it with npx

Using with Claude Desktop

Using the Published Package

Add this configuration to your Claude Desktop config file:

MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "smartsheet-dev-mcp": {
      "command": "npx",
      "args": ["@sekora/[email protected]"]
    }
  }
}

Local Development

For development, use the local build:

{
  "mcpServers": {
    "smartsheet-dev-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/smartsheet-dev-mcp/dist/index.js"],
      "cwd": "/absolute/path/to/smartsheet-dev-mcp"
    }
  }
}

Available Tools

1. GitlabReviewMrTool: Review GitLab merge requests with detailed analysis
2. GitlabExplainTraceTool: Explain GitLab CI/CD traces and pipeline details
3. TemporalSearchTemporalWorkflowsTool: Search for Temporal workflows
4. TemporalSummarizeWorkflowTool: Summarize Temporal workflow execution details

Installation & Configuration

1. Ensure you have Node.js >= 18.19.0 installed
2. Configure your GitLab and Temporal API endpoints as needed
3. Add the MCP server to your Claude Desktop configuration
4. Restart Claude Desktop to load the new MCP server

Building and Testing

1. Make changes to your tools
2. Run npm run build to compile
3. The server will automatically load your tools on startup

Learn More

• MCP Framework Github
• MCP Framework Docs