Airfocus MCP Server

A Model Context Protocol (MCP) server for Airfocus that allows fetching items, workspaces, and user information from Airfocus.

Features

• Get Items: Retrieve items by ID or alias (e.g., "DEV-123")
• List Workspaces: Browse available workspaces
• Search Items: Search for items across workspaces
• List Items: Get items within a specific workspace
• User Profile: Get current user profile information

Installation

Local Development

1. Clone the repository:

git clone https://github.com/username/airfocus-mcp.git
cd airfocus-mcp

2. Install dependencies:

npm install

3. Build the project:

npm run build

From NPM (when published)

npm install -g airfocus-mcp

From Source

git clone https://github.com/username/airfocus-mcp.git
cd airfocus-mcp
npm install
npm run build
npm link

Usage

Command Line

Run the MCP server with the following command:

airfocus-mcp --airfocusApiKey=your-api-key

Or with custom URL:

airfocus-mcp --airfocusUrl=https://app.airfocus.com --airfocusApiKey=your-api-key

Configuration

The server requires the following parameters:

• --airfocusApiKey or -k: Your Airfocus API key (required)
• --airfocusUrl or -u: Your Airfocus base URL (default: https://app.airfocus.com)

Getting an API Key

1. Log in to your Airfocus account
2. Go to your profile settings
3. Navigate to API Keys section
4. Create a new API key with appropriate permissions

Add as MCP server

Add to your MCP client configuration:

{
    "mcpServers": {
      "Airfocus MCP": {
         "command": "node",
         "args": ["/path/to/airfocus-mcp/dist/main.js", "--airfocusApiKey=your-api-key-here"]
      }
    }
}

Or if installed via npm:

{
    "mcpServers": {
      "Airfocus MCP": {
         "command": "npx",
         "args": ["airfocus-mcp", "--airfocusApiKey=your-api-key-here"]
      }
    }
}

Available Tools

getItem

Retrieve an item by ID or alias.

Parameters:

• identifier: Item ID (UUID) or alias (e.g., 'DEV-123')
• workspaceId: Workspace ID (UUID) - required if using item ID instead of alias

Example:

getItem(identifier: "DEV-123")
getItem(identifier: "550e8400-e29b-41d4-a716-446655440000", workspaceId: "workspace-id")

listWorkspaces

List available workspaces.

Parameters:

• limit: Maximum number of workspaces to return (default: 20)
• offset: Number of workspaces to skip (default: 0)

searchItems

Search for items across workspaces.

Parameters:

• query: Search query text
• workspaceId: Workspace ID to search within (optional)
• limit: Maximum number of items to return (default: 10)

listItems

List items within a specific workspace.

Parameters:

• workspaceId: Workspace ID (UUID)
• limit: Maximum number of items to return (default: 20)
• offset: Number of items to skip (default: 0)
• status: Filter by status (optional)

getProfile

Get current user profile information.

Parameters: None

Development

Project Structure

• main.ts: Main server implementation
• package.json: Project configuration and dependencies
• tsconfig.json: TypeScript configuration
• airfocus.openapi.json: Airfocus API specification

Building

To build the project:

npm run build

This will compile the TypeScript code into JavaScript in the dist directory.

API Integration

The server integrates with the Airfocus REST API using:

• Authentication: Bearer token authentication with API key
• Base URL: Configurable Airfocus instance URL
• Error Handling: Comprehensive error handling with helpful messages
• Response Format: Markdown-formatted responses for better readability

Publishing & Distribution

For Maintainers

1. Update version in package.json following semantic versioning:

   • Major: Breaking changes
   • Minor: New features (backward compatible)
   • Patch: Bug fixes

2. Build and test:

npm run build
npm test  # if tests are available

3. Create a release:

git tag v$(node -p "require('./package.json').version")
git push origin --tags

4. Publish to npm (if you have publishing rights):

npm publish

For Contributors

Please follow the contributing guidelines below for submitting changes.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contributing

We welcome contributions! Please follow these steps:

1. Fork the repository and clone your fork
2. Create a feature branch: git checkout -b feature/your-feature-name
3. Make your changes and ensure they work properly
4. Follow the existing code style and add appropriate error handling
5. Test your changes by building and running the server
6. Commit your changes using conventional commits:
   • feat: add new functionality
   • fix: resolve bug
   • docs: update documentation
   • refactor: improve code structure
7. Push to your fork: git push origin feature/your-feature-name
8. Open a Pull Request with a clear description of your changes

Development Guidelines

• Follow TypeScript best practices
• Add proper error handling for all API calls
• Include parameter validation using Zod schemas
• Format responses in readable Markdown
• Update documentation for any new tools or features

Reporting Issues

Please use the GitHub issue tracker to report bugs or request features. Include:

• Clear description of the issue
• Steps to reproduce (for bugs)
• Expected vs actual behavior
• Your environment details (Node.js version, OS, etc.)

Troubleshooting

Common Issues

1. Authentication Error: Ensure your API key is valid and has the required permissions
2. Network Error: Check your Airfocus URL and network connectivity
3. Item Not Found: Verify the item ID/alias exists and you have access to the workspace
4. Workspace Access: Ensure you have permissions to access the specified workspace

Community & Support

• 🐛 Bug Reports: GitHub Issues
• 💡 Feature Requests: GitHub Discussions
• 📖 MCP Documentation: Model Context Protocol
• 🔧 Airfocus API: Official API Documentation

Changelog

See CHANGELOG.md for detailed release notes and version history.