Skip to content

Commit 28ed7a7

Browse files
Tiberriver256Tiberriver256
committed
docs: improve documentation for NPX usage and development practices
1 parent 520949e commit 28ed7a7

File tree

5 files changed

+101
-350
lines changed

5 files changed

+101
-350
lines changed

‎CONTRIBUTING.md

+48
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,45 @@ We use GitHub to host code, to track issues and feature requests, as well as acc
2020
4. Push to the branch (`git push origin feature/amazing-feature`)
2121
5. Open a Pull Request
2222

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+
2362
## Commit Message Guidelines
2463

2564
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.
@@ -81,6 +120,15 @@ npm run commit
81120

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

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+
84132
## Automated Release Workflow
85133

86134
Our project uses an automated release workflow that leverages Conventional Commits to manage semantic versioning, generate changelogs, and create GitHub Releases.

‎README.md

+50-110
Original file line numberDiff line numberDiff line change
@@ -40,65 +40,55 @@ The server is structured around the Model Context Protocol (MCP) for communicati
4040
- Azure Identity credentials, or
4141
- Azure CLI login
4242

43-
### Installation
43+
### Running with NPX
4444

45-
1. Clone the repository:
45+
### Usage with Claude Desktop/Cursor AI
4646

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

52-
2. Install dependencies:
5349

54-
```
55-
npm install
56-
```
50+
#### Azure Identity Authentication
5751

58-
3. Set up your environment:
59-
60-
Option A: Using the automated setup script (recommended):
61-
62-
```
63-
chmod +x setup_env.sh
64-
./setup_env.sh
65-
```
66-
67-
This script will:
68-
69-
- Check for and install the Azure CLI DevOps extension if needed
70-
- Let you select from your available Azure DevOps organizations
71-
- Optionally set a default project
72-
- Create a Personal Access Token with the required permissions
73-
- Generate your `.env` file with the correct settings
74-
75-
Option B: Manual setup:
76-
77-
```
78-
cp .env.example .env
79-
```
80-
81-
Then edit the `.env` file with your Azure DevOps credentials (see Authentication section below).
82-
83-
### Running the Server
84-
85-
Build the TypeScript files:
52+
Be sure you are logged in to Azure CLI with `az login` then add the following:
8653

87-
```
88-
npm run build
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+
}
8968
```
9069

91-
Start the server:
9270

93-
```
94-
npm start
71+
#### Personal Access Token (PAT) Authentication
72+
73+
```json
74+
{
75+
"mcpServers": {
76+
"azureDevOps": {
77+
"command": "npx",
78+
"args": ["-y", "@tiberriver256/mcp-server-azure-devops"],
79+
"env": {
80+
"AZURE_DEVOPS_ORG_URL": "https://dev.azure.com/your-organization",
81+
"AZURE_DEVOPS_AUTH_METHOD": "pat",
82+
"AZURE_DEVOPS_PAT": "<YOUR_PAT>",
83+
"AZURE_DEVOPS_DEFAULT_PROJECT": "your-project-name"
84+
}
85+
}
86+
}
87+
}
9588
```
9689

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

99-
```
100-
npm run dev
101-
```
10292

10393
## Authentication Methods
10494

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

119109
Key environment variables include:
120110

121-
| Variable | Description | Required | Default |
122-
| ------------------------------ | --------------------------------------------------------------- | ------------------ | ------------------ |
111+
| Variable | Description | Required | Default |
112+
| ------------------------------ | ---------------------------------------------------------------------------------- | ------------------ | ------------------ |
123113
| `AZURE_DEVOPS_AUTH_METHOD` | Authentication method (`pat`, `azure-identity`, or `azure-cli`) - case-insensitive | No | `azure-identity` |
124-
| `AZURE_DEVOPS_ORG` | Azure DevOps organization name | No | Extracted from URL |
125-
| `AZURE_DEVOPS_ORG_URL` | Full URL to your Azure DevOps organization | Yes | - |
126-
| `AZURE_DEVOPS_PAT` | Personal Access Token (for PAT auth) | Only with PAT auth | - |
127-
| `AZURE_DEVOPS_DEFAULT_PROJECT` | Default project if none specified | No | - |
128-
| `AZURE_DEVOPS_API_VERSION` | API version to use | No | Latest |
129-
| `AZURE_AD_TENANT_ID` | Azure AD tenant ID (for AAD auth) | Only with AAD auth | - |
130-
| `AZURE_AD_CLIENT_ID` | Azure AD application ID (for AAD auth) | Only with AAD auth | - |
131-
| `AZURE_AD_CLIENT_SECRET` | Azure AD client secret (for AAD auth) | Only with AAD auth | - |
132-
| `PORT` | Server port | No | 3000 |
133-
| `HOST` | Server host | No | localhost |
134-
| `LOG_LEVEL` | Logging level (debug, info, warn, error) | No | info |
114+
| `AZURE_DEVOPS_ORG` | Azure DevOps organization name | No | Extracted from URL |
115+
| `AZURE_DEVOPS_ORG_URL` | Full URL to your Azure DevOps organization | Yes | - |
116+
| `AZURE_DEVOPS_PAT` | Personal Access Token (for PAT auth) | Only with PAT auth | - |
117+
| `AZURE_DEVOPS_DEFAULT_PROJECT` | Default project if none specified | No | - |
118+
| `AZURE_DEVOPS_API_VERSION` | API version to use | No | Latest |
119+
| `AZURE_AD_TENANT_ID` | Azure AD tenant ID (for AAD auth) | Only with AAD auth | - |
120+
| `AZURE_AD_CLIENT_ID` | Azure AD application ID (for AAD auth) | Only with AAD auth | - |
121+
| `AZURE_AD_CLIENT_SECRET` | Azure AD client secret (for AAD auth) | Only with AAD auth | - |
122+
| `LOG_LEVEL` | Logging level (debug, info, warn, error) | No | info |
135123

136124
## Troubleshooting Authentication
137125

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

180-
## Testing
181-
182-
### Unit Tests
183-
184-
Run unit tests with:
185-
186-
```bash
187-
npm run test:unit
188-
```
189-
190-
### Integration Tests
191-
192-
Integration tests require a connection to a real Azure DevOps instance. To run them:
193-
194-
1. Ensure your `.env` file is configured with valid Azure DevOps credentials:
195-
196-
```
197-
AZURE_DEVOPS_ORG_URL=https://dev.azure.com/your-organization
198-
AZURE_DEVOPS_PAT=your-personal-access-token
199-
AZURE_DEVOPS_DEFAULT_PROJECT=your-project-name
200-
```
201-
202-
2. Run the integration tests:
203-
```bash
204-
npm run test:integration
205-
```
206-
207-
### CI Environment
208-
209-
For running tests in CI environments (like GitHub Actions), see [CI Environment Setup](docs/ci-setup.md) for instructions on configuring secrets.
210-
211-
## Development
212-
213-
This project follows Test-Driven Development practices. Each new feature should:
214-
215-
1. Begin with a failing test
216-
2. Implement the minimal code to make the test pass
217-
3. Refactor while keeping tests green
218-
219-
## Release Process
220-
221-
This project uses [Conventional Commits](https://www.conventionalcommits.org/) to automate versioning and changelog generation. When contributing, please follow the commit message convention.
168+
## Contributing
222169

223-
To create a commit with the correct format, use:
224-
```bash
225-
npm run commit
226-
```
170+
Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines.
227171

228172
## License
229173

230174
MIT
231-
232-
## Contributing
233-
234-
Contributions are welcome! Please feel free to submit a Pull Request.

‎project-management/startup.xml

+3-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
<AiTaskAgent>
22
<GlobalRule alwaysApply="true">If an ANY point you get stuck, review troubleshooter.xml to help you troubleshoot the problem.</GlobalRule>
33
<GlobalRule alwaysApply="true">All new code creation should ALWAYS follow tdd-cycle.xml</GlobalRule>
4+
<GlobalRule alwaysApply="true">Tasks in todo.md are sorted in order of priority - ALWAYS pick the task from the top of the list.</GlobalRule>
45
<InitialSetup order="1">
56
<Step order="1">Read the dream team documentation at project-management/planning/the-dream-team.md to understand the team structure and roles</Step>
67
<Step order="2">Read all files in the project-management/planning directory to understand the project architecture, features, and structure</Step>
@@ -12,7 +13,7 @@
1213
- Available tools and integrations
1314
</Step>
1415
<Step order="4">Examine the current task list by viewing the project-management/task-management/ files todo.md and doing.md</Step>
15-
<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>
16+
<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>
1617
<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>
1718
<Step order="7">Read tdd-cycle.xml to understand the TDD cycle.</Step>
1819
<Step order="8">Start the research phase of TaskWorkflow.</Step>
@@ -54,5 +55,6 @@
5455
<Principle>Use the GitHub CLI (gh) for any GitHub-related tasks</Principle>
5556
<Principle>Use Puppeteer if web browsing is required</Principle>
5657
<Principle>If any task is unclear, stop and ask for clarification before proceeding</Principle>
58+
<Principle>Always take tasks from the top of todo.md as they are sorted in priority order</Principle>
5759
</WorkingPrinciples>
5860
</AiTaskAgent>

0 commit comments

Comments
 (0)