teamflect-mcp-server 1.0.3 → 1.0.5

package/.env.example

@@ -1,9 +1,9 @@
-# Teamflect API Configuration
-TEAMFLECT_API_KEY=your-api-key-here
-
-# Transport Configuration
-# Options: 'stdio' (default) or 'http'
-TRANSPORT=stdio
-
-# HTTP Server Configuration (only used when TRANSPORT=http)
-PORT=3000
+# Teamflect API Configuration
+TEAMFLECT_API_KEY=your-api-key-here
+
+# Transport Configuration
+# Options: 'stdio' (default) or 'http'
+TRANSPORT=stdio
+
+# HTTP Server Configuration (only used when TRANSPORT=http)
+PORT=3000

package/README.md

@@ -1,177 +1,196 @@
-# 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.
-
-## 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
-```
-
-## API Documentation
-
-https://api.teamflect.com/api/v1/
-
-## License
-
-MIT
+# 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
+```
+
+## API Documentation
+
+https://api.teamflect.com/api/v1/
+
+## License
+
+MIT

package/dist/tools/feedbacks.js

@@ -22,54 +22,54 @@ export function registerFeedbackTools(server, apiClient) {
     }).strict();
     server.registerTool("teamflect_get_feedbacks", {
         title: "Get Feedbacks",
-        description: `Retrieve a list of feedbacks from Teamflect based on filters.
-
-This tool searches for feedbacks matching the specified criteria. You can filter by status, the person the feedback is about, who submitted it, and date ranges. Results are paginated.
-
-Args:
-  - status (string, optional): Filter by feedback status
-  - aboutEmail (string, optional): Filter by the person the feedback is about (email address)
-  - submittedByEmail (string, optional): Filter by the person who submitted the feedback (email address)
-  - startDate (string, optional): Filter by submission start date in ISO format (YYYY-MM-DD)
-  - endDate (string, optional): Filter by submission end date in ISO format (YYYY-MM-DD)
-  - limit (number, optional): Maximum results to return, between 1-300 (default: 20)
-  - offset (number, optional): Number of results to skip for pagination (default: 0)
-  - response_format ('markdown' | 'json', optional): Output format (default: 'markdown')
-
-Returns:
-  For JSON format: Structured data with schema:
-  {
-    "total": number,
-    "count": number,
-    "offset": number,
-    "feedbacks": [
-      {
-        "feedbackId": string,
-        "about": {"displayName": string, "mail": string},
-        "status": string,
-        "submittedBy": {"displayName": string},
-        "createdAt": string,
-        "submittedAt": string,
-        "questions": [
-          {
-            "question": string,
-            "answer": string,
-            "additionalAnswer": string,
-            "questionType": string
-          }
-        ]
-      }
-    ],
-    "has_more": boolean,
-    "next_offset": number
-  }
-
-Examples:
-  - Use when: "Get all feedbacks about john@example.com" -> params with aboutEmail="john@example.com"
-  - Use when: "List feedbacks submitted this month" -> params with startDate/endDate filters
-
-Error Handling:
-  - Returns "Error: Authentication failed" if API key is invalid
+        description: `Retrieve a list of feedbacks from Teamflect based on filters.
+
+This tool searches for feedbacks matching the specified criteria. You can filter by status, the person the feedback is about, who submitted it, and date ranges. Results are paginated.
+
+Args:
+  - status (string, optional): Filter by feedback status
+  - aboutEmail (string, optional): Filter by the person the feedback is about (email address)
+  - submittedByEmail (string, optional): Filter by the person who submitted the feedback (email address)
+  - startDate (string, optional): Filter by submission start date in ISO format (YYYY-MM-DD)
+  - endDate (string, optional): Filter by submission end date in ISO format (YYYY-MM-DD)
+  - limit (number, optional): Maximum results to return, between 1-300 (default: 20)
+  - offset (number, optional): Number of results to skip for pagination (default: 0)
+  - response_format ('markdown' | 'json', optional): Output format (default: 'markdown')
+
+Returns:
+  For JSON format: Structured data with schema:
+  {
+    "total": number,
+    "count": number,
+    "offset": number,
+    "feedbacks": [
+      {
+        "feedbackId": string,
+        "about": {"displayName": string, "mail": string},
+        "status": string,
+        "submittedBy": {"displayName": string},
+        "createdAt": string,
+        "submittedAt": string,
+        "questions": [
+          {
+            "question": string,
+            "answer": string,
+            "additionalAnswer": string,
+            "questionType": string
+          }
+        ]
+      }
+    ],
+    "has_more": boolean,
+    "next_offset": number
+  }
+
+Examples:
+  - Use when: "Get all feedbacks about john@example.com" -> params with aboutEmail="john@example.com"
+  - Use when: "List feedbacks submitted this month" -> params with startDate/endDate filters
+
+Error Handling:
+  - Returns "Error: Authentication failed" if API key is invalid
   - Returns "Error: Rate limit exceeded" if too many requests`,
         inputSchema: GetFeedbacksInputSchema,
         annotations: {
@@ -227,23 +227,23 @@ Error Handling:
     }).strict();
     server.registerTool("teamflect_send_feedback_request", {
         title: "Send Feedback Request",
-        description: `Send a new feedback request in Teamflect.
-
-This tool creates and sends a feedback request to collect feedback about a person. The request includes questions that need to be answered.
-
-Args:
-  - aboutEmail (string, required): Email address of the person the feedback is about
-  - questions (array, required): Array of question objects, each with:
-    - question (string): Question text (1-1000 characters)
-    - questionType (string): Question type identifier
-  - dueDate (string, optional): Due date for feedback submission in ISO format (YYYY-MM-DD)
-  - response_format ('markdown' | 'json', optional): Output format (default: 'markdown')
-
-Returns:
-  The created feedback request with its ID and status.
-
-Error Handling:
-  - Returns "Error: Bad request" if required fields are missing or invalid
+        description: `Send a new feedback request in Teamflect.
+
+This tool creates and sends a feedback request to collect feedback about a person. The request includes questions that need to be answered.
+
+Args:
+  - aboutEmail (string, required): Email address of the person the feedback is about
+  - questions (array, required): Array of question objects, each with:
+    - question (string): Question text (1-1000 characters)
+    - questionType (string): Question type identifier
+  - dueDate (string, optional): Due date for feedback submission in ISO format (YYYY-MM-DD)
+  - response_format ('markdown' | 'json', optional): Output format (default: 'markdown')
+
+Returns:
+  The created feedback request with its ID and status.
+
+Error Handling:
+  - Returns "Error: Bad request" if required fields are missing or invalid
   - Returns "Error: Permission denied" if you don't have permission to send feedback requests`,
         inputSchema: SendFeedbackRequestInputSchema,
         annotations: {
@@ -297,24 +297,24 @@ Error Handling:
     }).strict();
     server.registerTool("teamflect_send_external_feedback_request", {
         title: "Send External Feedback Request",
-        description: `Send a new external feedback request in Teamflect.
-
-This tool creates and sends a feedback request to an external person (someone outside your organization) to collect feedback about a person.
-
-Args:
-  - aboutEmail (string, required): Email address of the person the feedback is about
-  - externalEmail (string, required): Email address of the external person to request feedback from
-  - questions (array, required): Array of question objects, each with:
-    - question (string): Question text (1-1000 characters)
-    - questionType (string): Question type identifier
-  - dueDate (string, optional): Due date for feedback submission in ISO format (YYYY-MM-DD)
-  - response_format ('markdown' | 'json', optional): Output format (default: 'markdown')
-
-Returns:
-  The created external feedback request with its ID and status.
-
-Error Handling:
-  - Returns "Error: Bad request" if required fields are missing or invalid
+        description: `Send a new external feedback request in Teamflect.
+
+This tool creates and sends a feedback request to an external person (someone outside your organization) to collect feedback about a person.
+
+Args:
+  - aboutEmail (string, required): Email address of the person the feedback is about
+  - externalEmail (string, required): Email address of the external person to request feedback from
+  - questions (array, required): Array of question objects, each with:
+    - question (string): Question text (1-1000 characters)
+    - questionType (string): Question type identifier
+  - dueDate (string, optional): Due date for feedback submission in ISO format (YYYY-MM-DD)
+  - response_format ('markdown' | 'json', optional): Output format (default: 'markdown')
+
+Returns:
+  The created external feedback request with its ID and status.
+
+Error Handling:
+  - Returns "Error: Bad request" if required fields are missing or invalid
   - Returns "Error: Permission denied" if you don't have permission to send external feedback requests`,
         inputSchema: SendExternalFeedbackRequestInputSchema,
         annotations: {

package/dist/tools/goals.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"goals.d.ts","sourceRoot":"","sources":["../../src/tools/goals.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAK9D;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,kBAAkB,GAAG,IAAI,CA4exF"}
+{"version":3,"file":"goals.d.ts","sourceRoot":"","sources":["../../src/tools/goals.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAK9D;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,kBAAkB,GAAG,IAAI,CAgfxF"}