npm package: @ssekora/smartsheet-dev-mcp
Description: SmartSheet Dev MCP
Latest version: 0.0.1

# 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

```bash
# 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:

```bash
# 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:

```typescript
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:

```bash
# 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:

```bash
# 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:

```bash
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

```bash
# 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:**
```bash
# 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:**
```bash
# Run validation to see specific issues
npm run validate

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

**Push failures:**
```bash
# 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:
   ```bash
   npm run build
   npm link
   gitlab  # Test your CLI locally
   ```

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

4. Publish your package:
   ```bash
   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`

```json
{
  "mcpServers": {
    "smartsheet-dev-mcp": {
      "command": "npx",
      "args": ["@sekora/smartsheet-dev-mcp@0.0.2"]
    }
  }
}
```

### Local Development

For development, use the local build:

```json
{
  "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](https://github.com/QuantGeekDev/mcp-framework)
- [MCP Framework Docs](https://mcp-framework.com)