Skip to content

Commit b5f36d0

Browse files
AzureDevOpsAPIAzureDevOpsAPI
authored
Add files via upload
0 parents  commit b5f36d0

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

64 files changed

+18355
-0
lines changed

‎CHANGELOG.md‎

Lines changed: 335 additions & 0 deletions
Large diffs are not rendered by default.

‎CONTRIBUTING.md‎

Lines changed: 160 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,160 @@
1+
# Contributing to Azure DevOps MCP Server
2+
3+
We love your input! We want to make contributing to Azure DevOps MCP Server as easy and transparent as possible, whether it's:
4+
5+
- Reporting a bug
6+
- Discussing the current state of the code
7+
- Submitting a fix
8+
- Proposing new features
9+
- Becoming a maintainer
10+
11+
## Development Process
12+
13+
We use GitHub to host code, to track issues and feature requests, as well as accept pull requests.
14+
15+
## Pull Requests
16+
17+
1. Fork the repository
18+
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
19+
3. Commit your changes (see Commit Message Guidelines below)
20+
4. Push to the branch (`git push origin feature/amazing-feature`)
21+
5. Open a Pull Request
22+
23+
## Development Practices
24+
25+
This project follows Test-Driven Development practices. Each new feature should:
26+
27+
1. Begin with a failing test
28+
2. Implement the minimal code to make the test pass
29+
3. Refactor while keeping tests green
30+
31+
## Testing
32+
33+
### Unit Tests
34+
35+
Run unit tests with:
36+
37+
```bash
38+
npm run test:unit
39+
```
40+
41+
### Integration Tests
42+
43+
Integration tests require a connection to a real Azure DevOps instance. To run them:
44+
45+
1. Ensure your `.env` file is configured with valid Azure DevOps credentials:
46+
47+
```
48+
AZURE_DEVOPS_ORG_URL=https://dev.azure.com/your-organization
49+
AZURE_DEVOPS_PAT=your-personal-access-token
50+
AZURE_DEVOPS_DEFAULT_PROJECT=your-project-name
51+
```
52+
53+
2. Run the integration tests:
54+
```bash
55+
npm run test:integration
56+
```
57+
58+
### CI Environment
59+
60+
For running tests in CI environments (like GitHub Actions), see [CI Environment Setup](docs/ci-setup.md) for instructions on configuring secrets.
61+
62+
## Commit Message Guidelines
63+
64+
We follow the [Conventional Commits](https://www.conventionalcommits.org/) specification for our commit messages. This leads to more readable messages that are easy to follow when looking through the project history and enables automatic versioning and changelog generation.
65+
66+
### Commit Message Format
67+
68+
Each commit message consists of a **header**, a **body**, and a **footer**. The header has a special format that includes a **type**, a **scope**, and a **subject**:
69+
70+
```
71+
<type>(<scope>): <subject>
72+
<BLANK LINE>
73+
<body>
74+
<BLANK LINE>
75+
<footer>
76+
```
77+
78+
The **header** is mandatory, while the **scope** of the header is optional.
79+
80+
### Type
81+
82+
Must be one of the following:
83+
84+
- **feat**: A new feature
85+
- **fix**: A bug fix
86+
- **docs**: Documentation only changes
87+
- **style**: Changes that do not affect the meaning of the code (white-space, formatting, etc)
88+
- **refactor**: A code change that neither fixes a bug nor adds a feature
89+
- **perf**: A code change that improves performance
90+
- **test**: Adding missing tests or correcting existing tests
91+
- **build**: Changes that affect the build system or external dependencies
92+
- **ci**: Changes to our CI configuration files and scripts
93+
- **chore**: Other changes that don't modify src or test files
94+
95+
### Subject
96+
97+
The subject contains a succinct description of the change:
98+
99+
- Use the imperative, present tense: "change" not "changed" nor "changes"
100+
- Don't capitalize the first letter
101+
- No period (.) at the end
102+
103+
### Body
104+
105+
The body should include the motivation for the change and contrast this with previous behavior.
106+
107+
### Footer
108+
109+
The footer should contain any information about **Breaking Changes** and is also the place to reference GitHub issues that this commit closes.
110+
111+
Breaking Changes should start with the word `BREAKING CHANGE:` with a space or two newlines. The rest of the commit message is then used for this.
112+
113+
### Using the Interactive Tool
114+
115+
To simplify the process of creating correctly formatted commit messages, we've set up a tool that will guide you through the process. Simply use:
116+
117+
```bash
118+
npm run commit
119+
```
120+
121+
This will start an interactive prompt that will help you generate a properly formatted commit message.
122+
123+
## Release Process
124+
125+
This project uses [Conventional Commits](https://www.conventionalcommits.org/) to automate versioning and changelog generation. When contributing, please follow the commit message convention.
126+
127+
To create a commit with the correct format, use:
128+
```bash
129+
npm run commit
130+
```
131+
132+
## Automated Release Workflow
133+
134+
Our project uses [Release Please](https://github.com/googleapis/release-please) to automate releases based on Conventional Commits. This approach manages semantic versioning, changelog generation, and GitHub Releases creation.
135+
136+
The workflow is automatically triggered on pushes to the `main` branch and follows this process:
137+
138+
1. Release Please analyzes commit messages since the last release
139+
2. If releasable changes are detected, it creates or updates a Release PR
140+
3. When the Release PR is merged, it:
141+
- Updates the version in package.json
142+
- Updates CHANGELOG.md with details of all changes
143+
- Creates a Git tag and GitHub Release
144+
- Publishes the package to npm
145+
146+
### Release PR Process
147+
148+
1. When commits with conventional commit messages are pushed to `main`, Release Please automatically creates a Release PR
149+
2. The Release PR contains all the changes since the last release with proper version bump based on commit types:
150+
- `feat:` commits trigger a minor version bump
151+
- `fix:` commits trigger a patch version bump
152+
- `feat!:` or `fix!:` commits with breaking changes trigger a major version bump
153+
3. Review the Release PR to ensure the changelog and version bump are correct
154+
4. Merge the Release PR to trigger the actual release
155+
156+
This automation ensures consistent and well-documented releases that accurately reflect the changes made since the previous release.
157+
158+
## License
159+
160+
By contributing, you agree that your contributions will be licensed under the project's license.

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2025 Micah Rairdon
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 205 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,205 @@
1+
# Azure DevOps MCP Server
2+
3+
A Model Context Protocol (MCP) server implementation for Azure DevOps, allowing AI assistants to interact with Azure DevOps APIs through a standardized protocol.
4+
5+
## Overview
6+
7+
This server implements the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) for Azure DevOps, enabling AI assistants like Claude to interact with Azure DevOps resources securely. The server acts as a bridge between AI models and Azure DevOps APIs, providing a standardized way to:
8+
9+
- Access and manage projects, work items, repositories, and more
10+
- Create and update work items, branches, and pull requests
11+
- Execute common DevOps workflows through natural language
12+
- Access repository content via standardized resource URIs
13+
- Safely authenticate and interact with Azure DevOps resources
14+
15+
## Server Structure
16+
17+
The server is structured around the Model Context Protocol (MCP) for communicating with AI assistants. It provides tools for interacting with Azure DevOps resources including:
18+
19+
- Projects
20+
- Work Items
21+
- Repositories
22+
- Pull Requests
23+
- Branches
24+
- Pipelines
25+
26+
### Core Components
27+
28+
- **AzureDevOpsServer**: Main server class that initializes the MCP server and registers tools
29+
- **Tool Handlers**: Modular functions for each Azure DevOps operation
30+
- **Configuration**: Environment-based configuration for organization URL, PAT, etc.
31+
32+
## Getting Started
33+
34+
### Prerequisites
35+
36+
- Node.js (v16+)
37+
- npm or yarn
38+
- Azure DevOps account with appropriate access
39+
- Authentication credentials (see [Authentication Guide](docs/authentication.md) for details):
40+
- Personal Access Token (PAT), or
41+
- Azure Identity credentials, or
42+
- Azure CLI login
43+
44+
### Running with NPX
45+
46+
### Usage with Claude Desktop/Cursor AI
47+
48+
To integrate with Claude Desktop or Cursor AI, add one of the following configurations to your configuration file.
49+
50+
#### Azure Identity Authentication
51+
52+
Be sure you are logged in to Azure CLI with `az login` then add the following:
53+
54+
```json
55+
{
56+
"mcpServers": {
57+
"azureDevOps": {
58+
"command": "npx",
59+
"args": ["-y", "@tiberriver256/mcp-server-azure-devops"],
60+
"env": {
61+
"AZURE_DEVOPS_ORG_URL": "https://dev.azure.com/your-organization",
62+
"AZURE_DEVOPS_AUTH_METHOD": "azure-identity",
63+
"AZURE_DEVOPS_DEFAULT_PROJECT": "your-project-name"
64+
}
65+
}
66+
}
67+
}
68+
```
69+
70+
#### Personal Access Token (PAT) Authentication
71+
72+
```json
73+
{
74+
"mcpServers": {
75+
"azureDevOps": {
76+
"command": "npx",
77+
"args": ["-y", "@tiberriver256/mcp-server-azure-devops"],
78+
"env": {
79+
"AZURE_DEVOPS_ORG_URL": "https://dev.azure.com/your-organization",
80+
"AZURE_DEVOPS_AUTH_METHOD": "pat",
81+
"AZURE_DEVOPS_PAT": "<YOUR_PAT>",
82+
"AZURE_DEVOPS_DEFAULT_PROJECT": "your-project-name"
83+
}
84+
}
85+
}
86+
}
87+
```
88+
89+
For detailed configuration instructions and more authentication options, see the [Authentication Guide](docs/authentication.md).
90+
91+
## Authentication Methods
92+
93+
This server supports multiple authentication methods for connecting to Azure DevOps APIs. For detailed setup instructions, configuration examples, and troubleshooting tips, see the [Authentication Guide](docs/authentication.md).
94+
95+
### Supported Authentication Methods
96+
97+
1. **Personal Access Token (PAT)** - Simple token-based authentication
98+
2. **Azure Identity (DefaultAzureCredential)** - Flexible authentication using the Azure Identity SDK
99+
3. **Azure CLI** - Authentication using your Azure CLI login
100+
101+
Example configuration files for each authentication method are available in the [examples directory](docs/examples/).
102+
103+
## Environment Variables
104+
105+
For a complete list of environment variables and their descriptions, see the [Authentication Guide](docs/authentication.md#configuration-reference).
106+
107+
Key environment variables include:
108+
109+
| Variable | Description | Required | Default |
110+
| ------------------------------ | ---------------------------------------------------------------------------------- | ---------------------------- | ---------------- |
111+
| `AZURE_DEVOPS_AUTH_METHOD` | Authentication method (`pat`, `azure-identity`, or `azure-cli`) - case-insensitive | No | `azure-identity` |
112+
| `AZURE_DEVOPS_ORG_URL` | Full URL to your Azure DevOps organization | Yes | - |
113+
| `AZURE_DEVOPS_PAT` | Personal Access Token (for PAT auth) | Only with PAT auth | - |
114+
| `AZURE_DEVOPS_DEFAULT_PROJECT` | Default project if none specified | No | - |
115+
| `AZURE_DEVOPS_API_VERSION` | API version to use | No | Latest |
116+
| `AZURE_TENANT_ID` | Azure AD tenant ID (for service principals) | Only with service principals | - |
117+
| `AZURE_CLIENT_ID` | Azure AD application ID (for service principals) | Only with service principals | - |
118+
| `AZURE_CLIENT_SECRET` | Azure AD client secret (for service principals) | Only with service principals | - |
119+
| `LOG_LEVEL` | Logging level (debug, info, warn, error) | No | info |
120+
121+
## Troubleshooting Authentication
122+
123+
For detailed troubleshooting information for each authentication method, see the [Authentication Guide](docs/authentication.md#troubleshooting-authentication-issues).
124+
125+
Common issues include:
126+
127+
- Invalid or expired credentials
128+
- Insufficient permissions
129+
- Network connectivity problems
130+
- Configuration errors
131+
132+
## Authentication Implementation Details
133+
134+
For technical details about how authentication is implemented in the Azure DevOps MCP server, see the [Authentication Guide](docs/authentication.md) and the source code in the `src/auth` directory.
135+
136+
## Available Tools
137+
138+
The Azure DevOps MCP server provides a variety of tools for interacting with Azure DevOps resources. For detailed documentation on each tool, please refer to the corresponding documentation.
139+
140+
### User Tools
141+
142+
- `get_me`: Get details of the authenticated user (id, displayName, email)
143+
144+
### Organization Tools
145+
146+
- `list_organizations`: List all accessible organizations
147+
148+
### Project Tools
149+
150+
- `list_projects`: List all projects in an organization
151+
- `get_project`: Get details of a specific project
152+
- `get_project_details`: Get comprehensive details of a project including process, work item types, and teams
153+
154+
### Repository Tools
155+
156+
- `list_repositories`: List all repositories in a project
157+
- `get_repository`: Get details of a specific repository
158+
- `get_repository_details`: Get detailed information about a repository including statistics and refs
159+
- `get_file_content`: Get content of a file or directory from a repository
160+
161+
### Work Item Tools
162+
163+
- `get_work_item`: Retrieve a work item by ID
164+
- `create_work_item`: Create a new work item
165+
- `update_work_item`: Update an existing work item
166+
- `list_work_items`: List work items in a project
167+
- `manage_work_item_link`: Add, remove, or update links between work items
168+
169+
### Search Tools
170+
171+
- `search_code`: Search for code across repositories in a project
172+
- `search_wiki`: Search for content across wiki pages in a project
173+
- `search_work_items`: Search for work items across projects in Azure DevOps
174+
175+
### Pipelines Tools
176+
177+
- `list_pipelines`: List pipelines in a project
178+
- `get_pipeline`: Get details of a specific pipeline
179+
- `trigger_pipeline`: Trigger a pipeline run with customizable parameters
180+
181+
### Wiki Tools
182+
183+
- `get_wikis`: List all wikis in a project
184+
- `get_wiki_page`: Get content of a specific wiki page as plain text
185+
186+
### Pull Requests Tools
187+
188+
- `create_pull_request`: Create a new pull request between branches in a repository
189+
- `list_pull_requests`: List and filter pull requests in a project or repository
190+
- `get_pull_request_comments`: Get comments and comment threads from a specific pull request
191+
- `add_pull_request_comment`: Add a comment to a pull request (reply to existing comments or create new threads)
192+
193+
For comprehensive documentation on all tools, see the [Tools Documentation](docs/tools/).
194+
195+
## Contributing
196+
197+
Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines.
198+
199+
## Star History
200+
201+
[![Star History Chart](https://api.star-history.com/svg?repos=tiberriver256/mcp-server-azure-devops&type=Date)](https://www.star-history.com/#tiberriver256/mcp-server-azure-devops&Date)
202+
203+
## License
204+
205+
MIT

‎commitlint.config.js‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
// commitlint.config.js
2+
module.exports = {
3+
extends: ['@commitlint/config-conventional'],
4+
};

0 commit comments

Comments
 (0)