Skip to content

docs: improve documentation for NPX usage and development practices #32

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Tiberriver256 merged 2 commits into from
Mar 26, 2025
Merged

docs: improve documentation for NPX usage and development practices #32

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
3af06b5
docs: improve documentation for NPX usage and development practices
Tiberriver256 Mar 26, 2025
cdcfde4
Merge branch 'main' into update-npx-usage-docs
Tiberriver256 Mar 26, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
48 changes: 48 additions & 0 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,45 @@ We use GitHub to host code, to track issues and feature requests, as well as acc
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## Development Practices

This project follows Test-Driven Development practices. Each new feature should:

1. Begin with a failing test
2. Implement the minimal code to make the test pass
3. Refactor while keeping tests green

## Testing

### Unit Tests

Run unit tests with:

```bash
npm run test:unit
```

### Integration Tests

Integration tests require a connection to a real Azure DevOps instance. To run them:

1. Ensure your `.env` file is configured with valid Azure DevOps credentials:

```
AZURE_DEVOPS_ORG_URL=https://dev.azure.com/your-organization
AZURE_DEVOPS_PAT=your-personal-access-token
AZURE_DEVOPS_DEFAULT_PROJECT=your-project-name
```

2. Run the integration tests:
```bash
npm run test:integration
```

### CI Environment

For running tests in CI environments (like GitHub Actions), see [CI Environment Setup](docs/ci-setup.md) for instructions on configuring secrets.

## Commit Message Guidelines

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.
Expand Down Expand Up @@ -81,6 +120,15 @@ npm run commit

This will start an interactive prompt that will help you generate a properly formatted commit message.

## Release Process

This project uses [Conventional Commits](https://www.conventionalcommits.org/) to automate versioning and changelog generation. When contributing, please follow the commit message convention.

To create a commit with the correct format, use:
```bash
npm run commit
```

## Automated Release Workflow

Our project uses an automated release workflow that leverages Conventional Commits to manage semantic versioning, generate changelogs, and create GitHub Releases.
Expand Down
160 changes: 50 additions & 110 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,65 +40,55 @@ The server is structured around the Model Context Protocol (MCP) for communicati
- Azure Identity credentials, or
- Azure CLI login

### Installation
### Running with NPX

1. Clone the repository:
### Usage with Claude Desktop/Cursor AI

```
git clone https://github.com/your-username/azure-devops-mcp.git
cd azure-devops-mcp
```
To integrate with Claude Desktop or Cursor AI, add one of the following configurations to your configuration file.

2. Install dependencies:

```
npm install
```
#### Azure Identity Authentication

3. Set up your environment:

Option A: Using the automated setup script (recommended):

```
chmod +x setup_env.sh
./setup_env.sh
```

This script will:

- Check for and install the Azure CLI DevOps extension if needed
- Let you select from your available Azure DevOps organizations
- Optionally set a default project
- Create a Personal Access Token with the required permissions
- Generate your `.env` file with the correct settings

Option B: Manual setup:

```
cp .env.example .env
```

Then edit the `.env` file with your Azure DevOps credentials (see Authentication section below).

### Running the Server

Build the TypeScript files:
Be sure you are logged in to Azure CLI with `az login` then add the following:

```
npm run build
```json
{
"mcpServers": {
"azureDevOps": {
"command": "npx",
"args": ["-y", "@tiberriver256/mcp-server-azure-devops"],
"env": {
"AZURE_DEVOPS_ORG_URL": "https://dev.azure.com/your-organization",
"AZURE_DEVOPS_AUTH_METHOD": "azure-identity",
"AZURE_DEVOPS_DEFAULT_PROJECT": "your-project-name"
}
}
}
}
```

Start the server:

```
npm start
#### Personal Access Token (PAT) Authentication

```json
{
"mcpServers": {
"azureDevOps": {
"command": "npx",
"args": ["-y", "@tiberriver256/mcp-server-azure-devops"],
"env": {
"AZURE_DEVOPS_ORG_URL": "https://dev.azure.com/your-organization",
"AZURE_DEVOPS_AUTH_METHOD": "pat",
"AZURE_DEVOPS_PAT": "<YOUR_PAT>",
"AZURE_DEVOPS_DEFAULT_PROJECT": "your-project-name"
}
}
}
}
```

For development with hot reloading:
For detailed configuration instructions and more authentication options, see the [Authentication Guide](docs/authentication.md).

```
npm run dev
```

## Authentication Methods

Expand All @@ -118,20 +108,18 @@ For a complete list of environment variables and their descriptions, see the [Au

Key environment variables include:

| Variable | Description | Required | Default |
| ------------------------------ | --------------------------------------------------------------- | ------------------ | ------------------ |
| Variable | Description | Required | Default |
| ------------------------------ | ---------------------------------------------------------------------------------- | ------------------ | ------------------ |
| `AZURE_DEVOPS_AUTH_METHOD` | Authentication method (`pat`, `azure-identity`, or `azure-cli`) - case-insensitive | No | `azure-identity` |
| `AZURE_DEVOPS_ORG` | Azure DevOps organization name | No | Extracted from URL |
| `AZURE_DEVOPS_ORG_URL` | Full URL to your Azure DevOps organization | Yes | - |
| `AZURE_DEVOPS_PAT` | Personal Access Token (for PAT auth) | Only with PAT auth | - |
| `AZURE_DEVOPS_DEFAULT_PROJECT` | Default project if none specified | No | - |
| `AZURE_DEVOPS_API_VERSION` | API version to use | No | Latest |
| `AZURE_AD_TENANT_ID` | Azure AD tenant ID (for AAD auth) | Only with AAD auth | - |
| `AZURE_AD_CLIENT_ID` | Azure AD application ID (for AAD auth) | Only with AAD auth | - |
| `AZURE_AD_CLIENT_SECRET` | Azure AD client secret (for AAD auth) | Only with AAD auth | - |
| `PORT` | Server port | No | 3000 |
| `HOST` | Server host | No | localhost |
| `LOG_LEVEL` | Logging level (debug, info, warn, error) | No | info |
| `AZURE_DEVOPS_ORG` | Azure DevOps organization name | No | Extracted from URL |
| `AZURE_DEVOPS_ORG_URL` | Full URL to your Azure DevOps organization | Yes | - |
| `AZURE_DEVOPS_PAT` | Personal Access Token (for PAT auth) | Only with PAT auth | - |
| `AZURE_DEVOPS_DEFAULT_PROJECT` | Default project if none specified | No | - |
| `AZURE_DEVOPS_API_VERSION` | API version to use | No | Latest |
| `AZURE_AD_TENANT_ID` | Azure AD tenant ID (for AAD auth) | Only with AAD auth | - |
| `AZURE_AD_CLIENT_ID` | Azure AD application ID (for AAD auth) | Only with AAD auth | - |
| `AZURE_AD_CLIENT_SECRET` | Azure AD client secret (for AAD auth) | Only with AAD auth | - |
| `LOG_LEVEL` | Logging level (debug, info, warn, error) | No | info |

## Troubleshooting Authentication

Expand Down Expand Up @@ -177,58 +165,10 @@ For repository-specific tool documentation, see the [Repositories Tools Guide](d
- `get_work_item`: Retrieve a work item by ID
- `create_work_item`: Create a new work item

## Testing

### Unit Tests

Run unit tests with:

```bash
npm run test:unit
```

### Integration Tests

Integration tests require a connection to a real Azure DevOps instance. To run them:

1. Ensure your `.env` file is configured with valid Azure DevOps credentials:

```
AZURE_DEVOPS_ORG_URL=https://dev.azure.com/your-organization
AZURE_DEVOPS_PAT=your-personal-access-token
AZURE_DEVOPS_DEFAULT_PROJECT=your-project-name
```

2. Run the integration tests:
```bash
npm run test:integration
```

### CI Environment

For running tests in CI environments (like GitHub Actions), see [CI Environment Setup](docs/ci-setup.md) for instructions on configuring secrets.

## Development

This project follows Test-Driven Development practices. Each new feature should:

1. Begin with a failing test
2. Implement the minimal code to make the test pass
3. Refactor while keeping tests green

## Release Process

This project uses [Conventional Commits](https://www.conventionalcommits.org/) to automate versioning and changelog generation. When contributing, please follow the commit message convention.
## Contributing

To create a commit with the correct format, use:
```bash
npm run commit
```
Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines.

## License

MIT

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.
4 changes: 3 additions & 1 deletion project-management/startup.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
<AiTaskAgent>
<GlobalRule alwaysApply="true">If an ANY point you get stuck, review troubleshooter.xml to help you troubleshoot the problem.</GlobalRule>
<GlobalRule alwaysApply="true">All new code creation should ALWAYS follow tdd-cycle.xml</GlobalRule>
<GlobalRule alwaysApply="true">Tasks in todo.md are sorted in order of priority - ALWAYS pick the task from the top of the list.</GlobalRule>
<InitialSetup order="1">
<Step order="1">Read the dream team documentation at project-management/planning/the-dream-team.md to understand the team structure and roles</Step>
<Step order="2">Read all files in the project-management/planning directory to understand the project architecture, features, and structure</Step>
Expand All @@ -12,7 +13,7 @@
- Available tools and integrations
</Step>
<Step order="4">Examine the current task list by viewing the project-management/task-management/ files todo.md and doing.md</Step>
<Step order="5">If there is a task in doing.md move directly into TaskWorkflow. If not take the next task from todo.md and move it to doing.md, removing it from todo.md. After moving the task you should extend it with a phase property to be used in TaskWorkflow and a section for notes and sub-tasks.</Step>
<Step order="5">If there is a task in doing.md move directly into TaskWorkflow. If not take the FIRST task from the top of todo.md and move it to doing.md, removing it from todo.md. Remember that tasks are sorted by priority with most important at the top. After moving the task you should extend it with a phase property to be used in TaskWorkflow and a section for notes and sub-tasks.</Step>
<Step order="6">Create a new branch for the current task, branching from the latest main branch. Use a descriptive name for the branch, related to the task, by running ./create_branch.sh &lt;branch_name&gt;.</Step>
<Step order="7">Read tdd-cycle.xml to understand the TDD cycle.</Step>
<Step order="8">Start the research phase of TaskWorkflow.</Step>
Expand Down Expand Up @@ -54,5 +55,6 @@
<Principle>Use the GitHub CLI (gh) for any GitHub-related tasks</Principle>
<Principle>Use Puppeteer if web browsing is required</Principle>
<Principle>If any task is unclear, stop and ask for clarification before proceeding</Principle>
<Principle>Always take tasks from the top of todo.md as they are sorted in priority order</Principle>
</WorkingPrinciples>
</AiTaskAgent>
Loading