VersionOne MCP Server

A simplified Model Context Protocol (MCP) server using FastMCP for VersionOne API integration. This server enables AI assistants to query VersionOne for stories, features (epics), and their details with structured output.

Features

The server provides four main tools with structured Pydantic models:

1. get_stories - Get a list of stories from VersionOne
2. get_story_details - Get detailed information about a specific story by ID
3. get_features - Get a list of features (Epics) from VersionOne
4. get_feature_details - Get detailed information about a specific feature by ID

Prerequisites

• Python 3.10 or higher
• uv package manager
• VersionOne access token
• Your VersionOne instance URL

Installation

1. Install uv (if not already installed):

curl -LsSf https://astral.sh/uv/install.sh | sh

2. Clone or download this project:

cd versionone-mcp-server

3. Install dependencies with uv:

uv sync

4. Configure your VersionOne credentials:

cp env-template.txt .env

5. Edit .env with your actual VersionOne details:

# Your VersionOne base URL (e.g., https://www7.v1host.com/V1Instance)
VERSIONONE_BASE_URL=https://your-v1-host.com/YourInstance

# Your VersionOne access token (recommended)
VERSIONONE_ACCESS_TOKEN=your-access-token-here

Getting Your VersionOne Access Token

1. Log into your VersionOne instance
2. Navigate to your profile settings
3. Go to the Applications page
4. Create a new access token
5. Copy the token to your .env file

Configuration

Environment Variables

• VERSIONONE_BASE_URL: Your VersionOne instance URL (e.g., https://www7.v1host.com/V1Instance)
• VERSIONONE_ACCESS_TOKEN: Your VersionOne access token (recommended method)

MCP Configuration

Add this server to your MCP client configuration:

{
  "mcpServers": {
    "versionone": {
      "command": "uv",
      "args": ["run", "server", "stdio"],
      "cwd": "/path/to/versionone-mcp-server",
      "env": {
        "VERSIONONE_BASE_URL": "https://your-v1-host.com/YourInstance",
        "VERSIONONE_ACCESS_TOKEN": "your-access-token-here"
      }
    }
  }
}

Usage

Running the Server

uv run server stdio

Available Tools

1. get_stories

Get a list of stories from VersionOne with optional filtering.

Parameters:

• filters (optional): Object containing query filters
  • where: Where clause for filtering (e.g., 'AssetState!="Dead"')
  • sel: Comma-separated list of attributes to select (e.g., 'Name,Number,Description')
  • sort: Sort order (e.g., 'Name')
• page_size (optional): Number of items per page (default: 20)
• page_start (optional): Starting page number (default: 0)

Example:

{
  "name": "get_stories",
  "arguments": {
    "filters": {
      "where": "AssetState!=\"Dead\"",
      "sel": "Name,Number,Description,Status"
    },
    "page_size": 10
  }
}

2. get_story_details

Get detailed information about a specific story by ID.

Parameters:

• story_id (required): The ID of the story (e.g., "Story:1234")
• attributes (optional): List of specific attributes to retrieve

Example:

{
  "name": "get_story_details",
  "arguments": {
    "story_id": "Story:1234",
    "attributes": ["Name", "Description", "Status", "Owner"]
  }
}

3. get_features

Get a list of features (Epics) from VersionOne with optional filtering.

Parameters:

• filters (optional): Object containing query filters
  • where: Where clause for filtering
  • sel: Comma-separated list of attributes to select
  • sort: Sort order
• page_size (optional): Number of items per page (default: 20)
• page_start (optional): Starting page number (default: 0)

Example:

{
  "name": "get_features",
  "arguments": {
    "filters": {
      "where": "AssetState!=\"Dead\"",
      "sel": "Name,Number,Description,Status"
    }
  }
}

4. get_feature_details

Get detailed information about a specific feature by ID.

Parameters:

• feature_id (required): The ID of the feature/epic (e.g., "Epic:1234")
• attributes (optional): List of specific attributes to retrieve

Example:

{
  "name": "get_feature_details",
  "arguments": {
    "feature_id": "Epic:1234",
    "attributes": ["Name", "Description", "Status", "Owner"]
  }
}

VersionOne API Reference

This MCP server is built on top of the VersionOne REST API. For more detailed information about:

• Asset types and their relationships
• Available attributes for filtering and selection
• Query syntax and filtering options
• Authentication methods

Please refer to the official VersionOne API documentation at: https://versionone.github.io/api-docs/

Common Asset Types

• Story: User stories and backlog items
• Epic: Features and large work items
• Defect: Bugs and issues
• Task: Development tasks
• Test: Test cases
• Scope: Projects
• Timebox: Sprints/Iterations

Common Attributes

• Name: The title/name of the item
• Number: The auto-generated number (e.g., S-1001)
• Description: Detailed description
• Status: Current status of the item
• Owner: Assigned team member
• AssetState: State of the asset (Active, Closed, etc.)
• CreateDate: When the item was created
• ChangeDate: When the item was last modified

Error Handling

The server includes comprehensive error handling for:

• Network connectivity issues
• Authentication failures
• Invalid API requests
• Missing or malformed parameters

Errors are logged and returned in a user-friendly format.

Development

Running in Development Mode

# Install development dependencies
uv sync --dev

# Run with debug logging
uv run server stdio

Testing

You can test the server using any MCP-compatible client or by running individual functions with the VersionOne API directly.

Security

• Always use access tokens instead of username/password when possible
• Keep your access tokens secure and rotate them regularly
• Use environment variables for sensitive configuration
• Never commit credentials to version control

Troubleshooting

Common Issues

1. "VersionOne client not initialized"

   • Check that your environment variables are set correctly
   • Verify your VersionOne URL format
   • Ensure your access token is valid

2. Authentication errors (401)

   • Verify your access token is correct and not expired
   • Check that your VersionOne URL is correct
   • Try creating a new access token

3. Network timeouts

   • Check your internet connection
   • Verify the VersionOne server is accessible
   • Try increasing the timeout in the code if needed

Debugging

Enable debug logging by setting the log level in the server code:

logging.basicConfig(level=logging.DEBUG)

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

This project is provided as-is for educational and development purposes.

Support

For issues related to:

• This MCP server: Create an issue in this repository
• VersionOne API: Refer to VersionOne documentation or support
• MCP protocol: Refer to the MCP specification documentation