@vm3jack/mcp-server-azure-devops 1.0.0

package/docs/important-knowledge/azure-devops-rest-api-research.md

@@ -0,0 +1,88 @@
+# Researching Azure DevOps REST APIs (Cloud + Server)
+
+Source of truth: clone and browse the MicrosoftDocs REST API specs repo (Swagger 2.0 JSON).
+If docs and specs disagree, treat specs as primary for request shapes and versions.
+Repo: https://github.com/MicrosoftDocs/vsts-rest-api-specs.git
+
+## Quick start
+
+- Prefer cloning to a temporary location (ex: /tmp). Ask the human partner for a preferred location.
+- Default path for this repo: ~/repos/vsts-rest-api-specs
+
+```bash
+# preferred: ask partner for target path
+git clone https://github.com/MicrosoftDocs/vsts-rest-api-specs.git /tmp/vsts-rest-api-specs
+```
+
+## Repo layout (core)
+
+```
+vsts-rest-api-specs/
+  specification/
+    <area>/
+      <version>/
+        <area>.json
+        httpExamples/
+```
+
+Notes:
+- Each `<area>` is an API area (build, git, wit, work, etc).
+- Each `<version>` is an API version folder.
+- Most version folders include a single `<area>.json` Swagger file and optional `httpExamples/`.
+- `httpExamples/` contains request/response JSON (file names include HTTP method + operation).
+
+## Versions: Services vs Server
+
+- Azure DevOps Services (cloud): numeric folders like `5.0`, `6.1`, `7.2`.
+- Azure DevOps Server (on‑prem): folders like `azure-devops-server-7.0`, `azure-devops-server-7.1`.
+- Older TFS: folders like `tfs-4.1`.
+
+Rule of thumb:
+- Start with the exact server version folder if it exists.
+- If missing, drop to the closest lower version for that area.
+- Server lags Services; some areas are Services-only.
+
+## How to find the right spec
+
+1. Identify area: use `ls specification` to find the service name.
+2. Pick version folder: cloud vs server rules above.
+3. Open `<area>.json` and inspect:
+   - `info.version` (often includes `-preview` and optional `.n`)
+   - `paths` (endpoints)
+   - `parameters` (look for `api-Version-*` entries; descriptions include exact `api-version` values)
+   - `definitions` (request/response models)
+4. Check `httpExamples/` for concrete request/response samples.
+5. Use path placeholders: `{organization}` (Services) maps to org; on‑prem maps to collection.
+
+## Helpful local searches
+
+```bash
+# find an area by name
+rg --files -g 'git.json' specification
+
+# scan endpoints for a keyword
+rg -n "_apis" specification/git/7.2/git.json
+
+# see path placeholders
+rg -n '\\{organization\\}|\\{project\\}' specification/build/7.2/build.json
+
+# find api-version parameters
+rg -n '"api-version"' specification/build/7.2/build.json
+
+# confirm area metadata
+rg -n 'x-ms-vss-(area|resource-area-id)' specification/build/7.2/build.json
+```
+
+## Azure DevOps Server (on‑prem) specifics
+
+- Specs still list `host: dev.azure.com` in many files; on‑prem uses your server host instead.
+- Base path may include a collection segment (ex: `/tfs/{collection}`); use your server's actual base URL.
+- Use the on‑prem version folder as the authority for routes and parameters.
+- `api-version` is still required; use the exact value from the on‑prem spec.
+- Check `httpExamples/` for base paths and collection/project shapes.
+
+## Extra tips
+
+- Many areas share naming: `build`, `git`, `wit`, `work`, `distributedTask`, `serviceEndpoint`, etc.
+- Preview APIs show `-preview` in `info.version`; expect breaking changes.
+- If you’re unsure which area owns an endpoint, search across specs with `rg -n`.

package/docs/important-knowledge/llm-tldr-cli.md

@@ -0,0 +1,37 @@
+# llm-tldr CLI usage (uv)
+
+Scope: CLI only. Skip MCP. Use uv instead of pip.
+
+## Install (uv)
+
+- Install once: `uv tool install llm-tldr`
+
+## Core workflow
+
+- `tldr tree <path>` for structure
+- `tldr structure <path> --lang typescript` for symbols
+- `tldr search "<regex>" <path>` for entry points
+- `tldr extract <file> --function <name> --lang typescript` for focused details
+- `tldr context <entry> --project . --lang typescript` for call graph context
+
+## Indexing + daemon
+
+- `tldr warm .` builds call graph cache
+- `tldr daemon status` check daemon
+- `tldr daemon notify <file> --project .` after edits (reindex after threshold)
+
+## Semantic search (optional, heavy download)
+
+- `tldr semantic index . --lang all --model all-MiniLM-L6-v2`
+- `tldr semantic search "<query>" --path . --lang typescript`
+
+## Example: URL-based server selection in this repo
+
+1) Locate entry points:
+   - `tldr search "serverUrl|organizationUrl|extractOrgFromUrl" src`
+2) Inspect extraction logic:
+   - `tldr extract src/features/users/get-me/feature.ts --function extractOrgFromUrl --lang typescript`
+   - `tldr extract src/features/search/search-code/feature.ts --function extractOrgFromUrl --lang typescript`
+3) Check org derivation:
+   - `tldr extract src/utils/environment.ts --function getOrgNameFromUrl --lang typescript`
+4) Summarize how URL patterns drive which host or org is used.

package/docs/npm-trusted-publishers-migration.md

@@ -0,0 +1,142 @@
+# NPM Trusted Publishers Migration Guide
+
+This document explains the migration from token-based NPM publishing to NPM Trusted Publishers (Provenance) authentication.
+
+## What Changed
+
+### Workflow Changes
+
+The `.github/workflows/release-please.yml` workflow has been updated to use NPM Trusted Publishers instead of token-based authentication:
+
+**Before:**
+```yaml
+- name: Publish to npm
+  run: npm publish --access public
+  env:
+    NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+```
+
+**After:**
+```yaml
+- name: Publish to npm
+  run: npm publish --provenance --access public
+```
+
+### Key Differences
+
+1. **No Secret Token Required**: The `NPM_TOKEN` secret is no longer needed
+2. **Provenance Flag**: Added `--provenance` flag to enable trusted publishing
+3. **OIDC Authentication**: Uses OpenID Connect (OIDC) tokens from GitHub Actions
+4. **Enhanced Security**: Provides cryptographic proof of package origin
+
+## Benefits of NPM Trusted Publishers
+
+1. **Improved Security**: No long-lived tokens that can be leaked or stolen
+2. **Supply Chain Transparency**: Automated provenance statements prove package authenticity
+3. **Reduced Maintenance**: No need to rotate or manage NPM tokens
+4. **Verifiable Builds**: Anyone can verify that packages were built by GitHub Actions from specific commits
+
+## NPM Configuration Required
+
+To complete the migration, you need to configure the package on npmjs.com:
+
+### Step 1: Log into NPM
+
+Go to https://www.npmjs.com/ and log in to your account.
+
+### Step 2: Configure Trusted Publishers
+
+1. Navigate to your package: https://www.npmjs.com/package/@tiberriver256/mcp-server-azure-devops
+2. Click on "Settings" tab
+3. Scroll to "Publishing access" section
+4. Click "Add trusted publisher"
+5. Select "GitHub Actions"
+6. Fill in the details:
+   - **Repository owner**: `Tiberriver256`
+   - **Repository name**: `mcp-server-azure-devops`
+   - **Workflow**: `release-please.yml`
+   - **Environment** (optional): Leave empty unless using GitHub environments
+7. Click "Add"
+
+### Step 3: Verify Configuration
+
+After adding the trusted publisher configuration:
+1. The workflow will authenticate using OIDC tokens
+2. No `NPM_TOKEN` secret is needed
+3. Publishes will include provenance attestations
+
+## GitHub Actions Requirements
+
+The workflow already has the necessary permissions configured:
+
+```yaml
+permissions:
+  contents: write
+  pull-requests: write
+  issues: write
+  id-token: write  # Required for OIDC authentication
+```
+
+The `id-token: write` permission allows GitHub Actions to generate OIDC tokens for authentication with NPM.
+
+## Verification
+
+After the next release, you can verify provenance is working:
+
+### Check Provenance on NPM
+
+1. Visit your package page on npmjs.com
+2. Look for the "Provenance" badge on the package version
+3. Click the badge to see the build details and GitHub Actions workflow information
+
+### Using npm CLI
+
+```bash
+# View provenance information for a specific version
+npm view @tiberriver256/mcp-server-azure-devops@VERSION --json | jq .dist.attestations
+
+# Or check the latest version
+npm view @tiberriver256/mcp-server-azure-devops --json | jq .dist.attestations
+```
+
+## Troubleshooting
+
+### Publishing Fails with "Cannot verify OIDC token"
+
+**Cause**: NPM Trusted Publishers is not configured for the package.
+
+**Solution**: Follow [Step 2: Configure Trusted Publishers](#step-2-configure-trusted-publishers) above.
+
+### Publishing Fails with "Missing id-token permission"
+
+**Cause**: The workflow doesn't have the `id-token: write` permission.
+
+**Solution**: This is already configured in the workflow. Ensure no environment-level permissions override it.
+
+### NPM Still Asking for Token
+
+**Cause**: The `--provenance` flag is not being used, or trusted publishers is not configured.
+
+**Solution**: 
+1. Verify the workflow includes `--provenance` flag
+2. Ensure trusted publishers is configured on npmjs.com
+
+## Rolling Back
+
+If you need to roll back to token-based publishing:
+
+1. Revert the workflow changes
+2. Add the `NPM_TOKEN` secret back to GitHub repository secrets
+3. Remove the `--provenance` flag from the publish command
+
+## Additional Resources
+
+- [NPM Provenance Documentation](https://docs.npmjs.com/generating-provenance-statements)
+- [GitHub Actions OIDC Documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)
+- [NPM Trusted Publishers Guide](https://github.blog/2023-04-19-introducing-npm-package-provenance/)
+
+## Next Steps
+
+1. **Configure NPM Trusted Publishers**: Follow the steps in [NPM Configuration Required](#npm-configuration-required)
+2. **Test the Workflow**: Create a test release or manually trigger the workflow to verify publishing works
+3. **Remove NPM_TOKEN Secret**: After confirming everything works, you can delete the `NPM_TOKEN` secret from GitHub repository settings (Settings > Secrets and variables > Actions)

package/docs/release-troubleshooting.md

@@ -0,0 +1,153 @@
+# Release Troubleshooting Guide
+
+This guide helps you resolve common issues with the release-please automation and npm publishing.
+
+## Table of Contents
+
+- [Understanding the Release Process](#understanding-the-release-process)
+- [Common Issues](#common-issues)
+  - [Failed npm Publish](#failed-npm-publish)
+  - [Release Already Exists](#release-already-exists)
+  - [Manual Release Needed](#manual-release-needed)
+- [Solutions](#solutions)
+  - [Re-publishing an Existing Release](#re-publishing-an-existing-release)
+  - [Force a New Release](#force-a-new-release)
+
+## Understanding the Release Process
+
+The release process uses [release-please](https://github.com/googleapis/release-please) to automate releases:
+
+1. **Automated PR Creation**: When commits are pushed to `main`, release-please analyzes conventional commits and creates/updates a release PR
+2. **Release Creation**: When the release PR is merged, release-please:
+   - Creates a GitHub release with the new version tag
+   - Updates `CHANGELOG.md`, `package.json`, and `.github/release-please-manifest.json`
+3. **npm Publishing**: After a release is created, the workflow automatically:
+   - Checks out the tagged version
+   - Installs dependencies
+   - Builds the package
+   - Publishes to npm using [NPM Trusted Publishers](https://docs.npmjs.com/generating-provenance-statements) with provenance (no NPM_TOKEN needed)
+
+## Common Issues
+
+### Failed npm Publish
+
+**Symptom**: GitHub release exists, but the package is not on npm.
+
+**Cause**: The npm publish step failed (e.g., OIDC authentication error, network issue, npm downtime, or GitHub Actions permissions issue).
+
+**How to verify**:
+```bash
+# Check if version exists on npm
+npm view @tiberriver256/mcp-server-azure-devops@0.1.44
+
+# Check latest version
+npm view @tiberriver256/mcp-server-azure-devops version
+```
+
+**Solution**: [Re-publish the existing release](#re-publishing-an-existing-release)
+
+### Release Already Exists
+
+**Symptom**: Trying to re-run the workflow, but all publish steps are skipped.
+
+**Cause**: Release-please tracks state via the manifest file (`.github/release-please-manifest.json`). If the version in the manifest matches `package.json`, it considers the release complete and doesn't set `release_created=true`.
+
+**Solution**: [Re-publish the existing release](#re-publishing-an-existing-release) or [Force a new release](#force-a-new-release)
+
+### Manual Release Needed
+
+**Symptom**: Need to publish a hotfix or re-release immediately.
+
+**Solution**: [Re-publish the existing release](#re-publishing-an-existing-release)
+
+## Solutions
+
+### Re-publishing an Existing Release
+
+Use this when a GitHub release exists but npm publish failed. This will publish the existing tagged version to npm without creating a new release.
+
+**Steps**:
+
+1. Go to the [Actions tab](../../actions/workflows/release-please.yml) in GitHub
+2. Click "Run workflow" dropdown (you'll see this on the right side)
+3. Enter the **full git tag** in the "tag" field (e.g., `mcp-server-azure-devops-v0.1.44`)
+   - Find tags in the [releases page](../../releases) or [tags page](../../tags)
+4. Click "Run workflow"
+
+**What this does**:
+- Checks out the exact code from that tag
+- Builds the package
+- Publishes to npm
+- Does NOT create a new GitHub release
+- Does NOT modify version files or CHANGELOG
+
+**Example**:
+```
+Tag: mcp-server-azure-devops-v0.1.44
+```
+
+### Force a New Release
+
+Use this when you need to create a completely new release (incrementing the version number).
+
+**Option 1: Let release-please handle it (Recommended)**
+
+1. Make a new commit with conventional commit format:
+   ```bash
+   git commit --allow-empty -m "chore: trigger new release"
+   git push origin main
+   ```
+
+2. Release-please will create a new release PR
+3. Merge the PR to trigger the release
+
+**Option 2: Manual version bump**
+
+1. Update version in `package.json`:
+   ```bash
+   npm version patch  # for 0.1.44 -> 0.1.45
+   # or
+   npm version minor  # for 0.1.44 -> 0.2.0
+   # or
+   npm version major  # for 0.1.44 -> 1.0.0
+   ```
+
+2. Update `.github/release-please-manifest.json` to match the new version
+
+3. Update `CHANGELOG.md` with the new version section
+
+4. Commit and push:
+   ```bash
+   git add package.json package-lock.json .github/release-please-manifest.json CHANGELOG.md
+   git commit -m "chore: release v0.1.45"
+   git push origin main
+   ```
+
+5. Create a tag and release manually:
+   ```bash
+   git tag mcp-server-azure-devops-v0.1.45
+   git push origin mcp-server-azure-devops-v0.1.45
+   ```
+
+6. Then use [Re-publish the existing release](#re-publishing-an-existing-release) to publish to npm
+
+## Verification
+
+After publishing, verify the package is available:
+
+```bash
+# Check specific version
+npm view @tiberriver256/mcp-server-azure-devops@0.1.44
+
+# Check latest version
+npm view @tiberriver256/mcp-server-azure-devops version
+
+# Try installing
+npm install @tiberriver256/mcp-server-azure-devops@0.1.44
+```
+
+## Additional Resources
+
+- [Release Please Documentation](https://github.com/googleapis/release-please)
+- [Conventional Commits](https://www.conventionalcommits.org/)
+- [npm Publishing Guide](https://docs.npmjs.com/cli/v9/commands/npm-publish)

package/docs/testing/README.md

@@ -0,0 +1,140 @@
+# Testing Trophy Approach
+
+## Overview
+
+This project follows the Testing Trophy approach advocated by Kent C. Dodds instead of the traditional Testing Pyramid. The Testing Trophy emphasizes tests that provide higher confidence with less maintenance cost, focusing on how users actually interact with our software.
+
+![Testing Trophy Diagram](https://res.cloudinary.com/kentcdodds-com/image/upload/f_auto,q_auto,w_1600/v1625032020/kentcdodds.com/blog/the-testing-trophy-and-testing-classifications/trophy_wx9aen.png)
+
+## Key Principles
+
+1. **"The more your tests resemble the way your software is used, the more confidence they can give you."** - Kent C. Dodds
+2. Focus on testing behavior and interfaces rather than implementation details
+3. Maximize return on investment where "return" is confidence and "investment" is time
+4. Use arrange/act/assert pattern for all tests
+5. Co-locate tests with the code they test following Feature Sliced Design
+
+## Test Types
+
+### Static Analysis (The Base)
+
+- TypeScript for type checking
+- ESLint for code quality and consistency
+- Runtime type checking with Zod
+- Formatter (Prettier)
+
+These tools catch many issues before tests are even run and provide immediate feedback during development.
+
+### Unit Tests (Small Layer)
+
+- Located in `*.spec.unit.ts` files
+- Co-located with the code they test
+- Focus on testing complex business logic in isolation
+- Minimal mocking where necessary
+- Run with `npm run test:unit`
+
+Unit tests should be used sparingly for complex logic that requires isolated testing. We don't aim for 100% coverage with unit tests.
+
+### Integration Tests (Main Focus)
+
+- Located in `*.spec.int.ts` files
+- Co-located with the features they test
+- Test how modules work together
+- Focus on testing behavior, not implementation
+- Run with `npm run test:int`
+
+These provide the bulk of our test coverage and confidence. They verify that different parts of the system work together correctly.
+
+### End-to-End Tests (Small Cap)
+
+- Located in `*.spec.e2e.ts` files
+- **Only exists at the server level** (e.g., `server.spec.e2e.ts`) where they use the MCP client
+- Test complete user flows across the entire application
+- Provide the highest confidence but are slower and more costly to maintain
+- Run with `npm run test:e2e`
+
+End-to-end tests should only be created for critical user journeys that span the entire application. They should use the MCP client from `@modelcontextprotocol/sdk` to test the server as a black box, similar to how real users would interact with it.
+
+For testing interactions with external APIs like Azure DevOps, use integration tests (`*.spec.int.ts`) instead, which are co-located with the feature implementations.
+
+## Test File Naming Convention
+
+- `*.spec.unit.ts` - For minimal unit tests (essential logic only)
+- `*.spec.int.ts` - For integration tests (main focus)
+- `*.spec.e2e.ts` - For end-to-end tests
+
+## Test Location
+
+We co-locate unit and integration tests with the code they're testing following Feature Sliced Design principles:
+
+```
+src/
+  features/
+    feature-name/
+      feature.ts
+      feature.spec.unit.ts   # Unit tests
+      feature.spec.int.ts    # Integration tests
+```
+
+E2E tests are only located at the server level since they test the full application:
+
+```
+src/
+  server.ts
+  server.spec.e2e.ts   # E2E tests using the MCP client
+```
+
+This way, tests stay close to the code they're testing, making it easier to:
+- Find tests when working on a feature
+- Understand the relationship between tests and code
+- Refactor code and tests together
+- Maintain consistency between implementations and tests
+
+## The Arrange/Act/Assert Pattern
+
+All tests should follow the Arrange/Act/Assert pattern:
+
+```typescript
+test('should do something', () => {
+  // Arrange - set up the test
+  const input = 'something';
+  
+  // Act - perform the action being tested
+  const result = doSomething(input);
+  
+  // Assert - check that the action had the expected result
+  expect(result).toBe('expected output');
+});
+```
+
+## Running Tests
+
+- Run all tests: `npm test`
+- Run unit tests: `npm run test:unit`
+- Run integration tests: `npm run test:int`
+- Run E2E tests: `npm run test:e2e`
+
+## CI/CD Integration
+
+Our CI/CD pipeline runs all test levels to ensure code quality:
+
+1. Static analysis with TypeScript and ESLint
+2. Unit tests
+3. Integration tests
+4. End-to-end tests
+
+## Best Practices
+
+1. Focus on integration tests for the bulk of your test coverage
+2. Write unit tests only for complex business logic
+3. Avoid testing implementation details
+4. Use real dependencies when possible rather than mocks
+5. Keep E2E tests focused on critical user flows
+6. Use the arrange/act/assert pattern consistently
+7. Co-locate tests with the code they're testing
+
+## References
+
+- [The Testing Trophy and Testing Classifications](https://kentcdodds.com/blog/the-testing-trophy-and-testing-classifications) by Kent C. Dodds
+- [Testing of Microservices](https://engineering.atspotify.com/2018/01/testing-of-microservices/) (Testing Honeycomb approach) by Spotify Engineering
+- [Feature Sliced Design](https://feature-sliced.design/) for co-location of tests with feature implementations 

package/docs/testing/setup.md

@@ -0,0 +1,72 @@
+# Testing Setup Guide
+
+## Environment Variables
+
+Tests that interact with Azure DevOps APIs (integration and e2e tests) require environment variables to run properly. These variables are automatically loaded from your `.env` file during test execution.
+
+Required variables:
+```
+AZURE_DEVOPS_ORG_URL=https://dev.azure.com/your-organization
+AZURE_DEVOPS_PAT=your-personal-access-token
+AZURE_DEVOPS_DEFAULT_PROJECT=your-project-name
+```
+
+## Test Structure
+
+Tests in this project are co-located with the code they're testing:
+
+```
+src/
+  features/
+    feature-name/
+      feature.ts
+      feature.spec.unit.ts   # Unit tests
+      feature.spec.int.ts    # Integration tests
+```
+
+E2E tests are only located at the server level:
+
+```
+src/
+  server.ts
+  server.spec.e2e.ts   # E2E tests
+```
+
+## Import Pattern
+
+We use path aliases to make imports cleaner and easier to maintain. Instead of relative imports like:
+
+```typescript
+import { someFunction } from '../../../../shared/utils';
+```
+
+You can use the `@/` path alias:
+
+```typescript
+import { someFunction } from '@/shared/utils';
+```
+
+### Test Helpers
+
+Test helpers are located in a centralized location for all tests:
+
+```typescript
+import { getTestConnection, shouldSkipIntegrationTest } from '@/shared/test/test-helpers';
+```
+
+## Running Tests
+
+- Unit tests: `npm run test:unit`
+- Integration tests: `npm run test:int`
+- E2E tests: `npm run test:e2e`
+- All tests: `npm test`
+
+## VSCode Integration
+
+The project includes VSCode settings that:
+
+1. Show proper test icons for `*.spec.*.ts` files
+2. Enable file nesting to group test files with their implementation
+3. Configure TypeScript to prefer path aliases over relative imports
+
+These settings are stored in `.vscode/settings.json`.