# Teamflect MCP Server

MCP (Model Context Protocol) server for Teamflect API integration. Provides tools to interact with Teamflect's performance management features including goals, feedback, recognitions, reviews, tasks, and user management.

## Features

- **Goals**: Get, create, update progress, and comment on goals
- **Feedbacks**: Get feedbacks, send feedback requests (internal and external)
- **Recognitions**: Get, search, and create recognitions
- **Reviews**: Get reviews with filtering
- **Tasks**: Get tasks and individual task details
- **Users**: Get users, get user by email, update user attributes, and get available roles

## Prerequisites

- Node.js >= 18
- Teamflect API key from https://admin.teamflect.com
- MCP client (Claude Desktop or Cursor IDE)

## Installation

You can use it directly with `npx` (no installation needed) or install it globally.

### Option 1: Use with npx (Recommended - No Installation)

No installation required. Just use `npx` in your MCP client configuration (see Configuration section below).

### Option 2: Install Globally

```bash
npm install -g teamflect-mcp-server
```

### Option 3: Install from Source

For development or customization:

```bash
git clone <repository-url>
cd teamflect-mcp-server
npm install
npm run build
```

## Configuration

### 1. Get Your API Key

Get your API key from https://admin.teamflect.com → Settings → API

### 2. Configure MCP Client

**Claude Desktop:** Edit `claude_desktop_config.json`
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Linux:** `~/.config/Claude/claude_desktop_config.json`

**Cursor IDE:** Settings (Ctrl+,) → Search "MCP" → Edit settings.json

**Recommended Configuration (using npm package):**
```json
{
  "mcpServers": {
    "teamflect": {
      "command": "npx",
      "args": ["-y", "teamflect-mcp-server"],
      "env": {
        "TEAMFLECT_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

**Alternative Configuration (source installation only):**
```json
{
  "mcpServers": {
    "teamflect": {
      "command": "node",
      "args": ["/absolute/path/to/teamflect-mcp-server/dist/index.js"],
      "env": {
        "TEAMFLECT_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

**Windows path format:** Use double backslashes `\\` in JSON: `"C:\\path\\to\\teamflect-mcp-server\\dist\\index.js"`

### 3. Restart Your MCP Client

After configuration, completely close and restart Claude Desktop or Cursor IDE.

## Updating

**If using `npx` (recommended):** Cursor automatically uses the latest published version each time it starts. No action needed - just restart Cursor after a new version is published.

**If installed globally:** Update manually:
```bash
npm install -g teamflect-mcp-server@latest
```
Then restart Cursor IDE or Claude Desktop.

**If installed from source:** Pull updates and rebuild:
```bash
cd /path/to/teamflect-mcp-server
git pull
npm install
npm run build
```
Then restart your MCP client.

## Usage Examples

- "Get all users from Teamflect"
- "Get user john.doe@example.com"
- "Get all goals"
- "Create a new goal for Q1 2025"
- "Get all feedbacks"
- "Search for recognitions"

## Available Tools

### Goals
- `teamflect_get_goals` - Get list of goals with filtering
- `teamflect_get_goal` - Get a specific goal by ID
- `teamflect_create_goal` - Create a new goal
- `teamflect_update_goal_progress` - Update goal progress
- `teamflect_comment_goal` - Add a comment to a goal

### Feedbacks
- `teamflect_get_feedbacks` - Get list of feedbacks
- `teamflect_send_feedback_request` - Send internal feedback request
- `teamflect_send_external_feedback_request` - Send external feedback request

### Recognitions
- `teamflect_get_recognition` - Get a specific recognition by ID
- `teamflect_search_recognitions` - Search recognitions
- `teamflect_create_recognition` - Create a new recognition

### Reviews
- `teamflect_get_reviews` - Get list of reviews with filtering

### Tasks
- `teamflect_get_tasks` - Get list of tasks
- `teamflect_get_task` - Get a specific task by ID

### Users
- `teamflect_get_users` - Get list of users with filtering and pagination
- `teamflect_get_user` - Get a specific user by email
- `teamflect_update_user` - Update user attributes
- `teamflect_get_roles` - Get available user roles

## Troubleshooting

**Server not starting:**
- Check Node.js version: `node --version` (should be >= 18)
- For source installation: Run `npm run build` and verify `dist/index.js` exists

**Package not found:**
- Verify package is published: `npm view teamflect-mcp-server`
- Check npm registry: `npm config get registry` (should be https://registry.npmjs.org/)
- Ensure you're connected to the internet

**MCP client doesn't see server:**
- Verify JSON syntax is valid (use https://jsonlint.com)
- For source installation: Ensure `dist/index.js` exists (run `npm run build`)
- Restart MCP client completely

**Tools not working:**
- Verify API key is correct and has necessary permissions
- Test API directly: `curl https://api.teamflect.com/api/v1/user/getUsers -H "Authorization: Bearer YOUR_API_KEY"`

## Environment Variables

- `TEAMFLECT_API_KEY` (required): Your Teamflect API key
- `TRANSPORT` (optional): `stdio` (default) or `http`
- `PORT` (optional): Port for HTTP transport (default: 3000)

## Development

```bash
npm run build    # Build the project
npm run dev      # Run in development mode with watch
npm start        # Run the server
```

### Important: API Endpoint Guidelines

**CRITICAL: Never assume API endpoints.** When adding new API integrations:

1. **Search the codebase first** - Look for existing endpoint patterns
2. **Check API documentation** - Review https://api.teamflect.com/api/v1/
3. **Ask if unsure** - Always confirm the correct endpoint with the user before implementing

See [CONTRIBUTING.md](./CONTRIBUTING.md) for detailed guidelines.

### Publishing to npm

If you encounter 2FA authentication issues when publishing to npmjs.org, use this workaround:

1. First, logout from the command line:
   ```bash
   npm logout
   ```

2. Create a granular token in the npm web interface:
   - Go to https://www.npmjs.com/settings/YOUR_USERNAME/tokens
   - Click "Generate New Token"
   - Select "Automation" or "Publish" type
   - Check "Bypass 2FA" option
   - Copy the generated token

3. Set the token using npm config:
   ```bash
   npm config set //registry.npmjs.org/:_authToken npm_yournewtokenhere
   ```

4. Publish the package:
   ```bash
   npm publish
   ```

This workaround allows publishing without requiring 2FA OTP codes during the publish process.

## API Documentation

https://api.teamflect.com/api/v1/

## License

MIT