@vm3jack/mcp-server-azure-devops 1.0.0

package/docs/tools/resources.md

@@ -0,0 +1,133 @@
+# Azure DevOps Resource URIs
+
+In addition to tools, the Azure DevOps MCP server provides access to resources via standardized URI patterns. Resources allow AI assistants to directly reference and retrieve content from Azure DevOps repositories using simple, predictable URLs.
+
+## Repository Content Resources
+
+The server supports accessing files and directories from Git repositories using the following resource URI patterns.
+
+### Available Resource URI Templates
+
+| Resource Type | URI Template | Description |
+| ------------- | ------------ | ----------- |
+| Default Branch Content | `ado://{organization}/{project}/{repo}/contents{/path*}` | Access file or directory content from the default branch |
+| Branch-Specific Content | `ado://{organization}/{project}/{repo}/branches/{branch}/contents{/path*}` | Access content from a specific branch |
+| Commit-Specific Content | `ado://{organization}/{project}/{repo}/commits/{commit}/contents{/path*}` | Access content from a specific commit |
+| Tag-Specific Content | `ado://{organization}/{project}/{repo}/tags/{tag}/contents{/path*}` | Access content from a specific tag |
+| Pull Request Content | `ado://{organization}/{project}/{repo}/pullrequests/{prId}/contents{/path*}` | Access content from a pull request |
+
+### URI Components
+
+- `{organization}`: Your Azure DevOps organization name
+- `{project}`: The project name or ID
+- `{repo}`: The repository name or ID
+- `{path*}`: The path to the file or directory within the repository (optional)
+- `{branch}`: The name of a branch
+- `{commit}`: The SHA-1 hash of a commit
+- `{tag}`: The name of a tag
+- `{prId}`: The ID of a pull request
+
+## Examples
+
+### Accessing Files from the Default Branch
+
+To access the content of a file in the default branch:
+
+```
+ado://myorg/MyProject/MyRepo/contents/src/index.ts
+```
+
+This retrieves the content of `index.ts` from the `src` directory in the default branch.
+
+### Accessing Directory Content
+
+To list the contents of a directory:
+
+```
+ado://myorg/MyProject/MyRepo/contents/src
+```
+
+This returns a JSON array containing information about all items in the `src` directory.
+
+### Accessing Content from a Specific Branch
+
+To access content from a feature branch:
+
+```
+ado://myorg/MyProject/MyRepo/branches/feature/new-ui/contents/src/index.ts
+```
+
+This retrieves the content of `index.ts` from the `feature/new-ui` branch.
+
+### Accessing Content from a Specific Commit
+
+To access content at a specific commit:
+
+```
+ado://myorg/MyProject/MyRepo/commits/a1b2c3d4e5f6g7h8i9j0/contents/src/index.ts
+```
+
+This retrieves the version of `index.ts` at the specified commit.
+
+### Accessing Content from a Tag
+
+To access content from a tagged release:
+
+```
+ado://myorg/MyProject/MyRepo/tags/v1.0.0/contents/README.md
+```
+
+This retrieves the README.md file from the v1.0.0 tag.
+
+### Accessing Content from a Pull Request
+
+To access content from a pull request:
+
+```
+ado://myorg/MyProject/MyRepo/pullrequests/42/contents/src/index.ts
+```
+
+This retrieves the version of `index.ts` from pull request #42.
+
+## Implementation Details
+
+When a resource URI is requested, the server:
+
+1. Parses the URI to extract the components (organization, project, repository, path, etc.)
+2. Establishes a connection to Azure DevOps using the configured authentication method
+3. Determines if a specific version (branch, commit, tag) is requested
+4. Uses the `getFileContent` functionality to retrieve the content
+5. Returns the content with the appropriate MIME type
+
+## Response Format
+
+Responses are returned with the appropriate MIME type based on the file extension. For example:
+
+- `.ts`, `.tsx` files: `application/typescript`
+- `.js` files: `application/javascript`
+- `.json` files: `application/json`
+- `.md` files: `text/markdown`
+- `.txt` files: `text/plain`
+- `.html`, `.htm` files: `text/html`
+- Image files (`.png`, `.jpg`, `.gif`, etc.): appropriate image MIME types
+
+For directories, the content is returned as a JSON array with MIME type `application/json`.
+
+## Error Handling
+
+The resource handler may throw the following errors:
+
+- `AzureDevOpsResourceNotFoundError`: If the specified resource cannot be found (project, repository, path, or version)
+- `AzureDevOpsAuthenticationError`: If authentication fails
+- `AzureDevOpsValidationError`: If the URI format is invalid
+- Other errors: For unexpected issues
+
+## Related Tools
+
+While resource URIs provide direct access to repository content, you can also use the following tools for more advanced operations:
+
+- `get_file_content`: Get content of a file or directory with more options and metadata
+- `get_repository`: Get details about a specific repository
+- `get_repository_details`: Get comprehensive repository information including statistics and refs
+- `list_repositories`: List all repositories in a project
+- `search_code`: Search for code in repositories 

package/docs/tools/search.md

@@ -0,0 +1,165 @@
+# Search Tools
+
+This document describes the search tools available in the Azure DevOps MCP server.
+
+## Azure DevOps Services vs Server base URLs
+
+- **Azure DevOps Services (cloud)** uses the dedicated Search host: `https://almsearch.dev.azure.com/{organization}`.
+- **Azure DevOps Server (on-prem)** hosts Search under the same collection URL you use for the core APIs: `https://{server}/{virtualDir?}/{collection}`.
+
+For Azure DevOps Server, set `AZURE_DEVOPS_ORG_URL` to the **collection URL** (not a project URL). Project-level URLs are ambiguous on Server installs with custom virtual directories and are not supported.
+
+Example:
+
+```bash
+AZURE_DEVOPS_ORG_URL=https://server:8080/tfs/DefaultCollection
+```
+
+## search_code
+
+The `search_code` tool allows you to search for code across repositories in an Azure DevOps project. It uses the Azure DevOps Search API to find code matching your search criteria and can optionally include the full content of the files in the results.
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| searchText | string | Yes | The text to search for in the code |
+| organizationId | string | No | Optional organization override (defaults to the organization in `AZURE_DEVOPS_ORG_URL`) |
+| projectId | string | Yes* | The ID or name of the project to search in. Required unless `AZURE_DEVOPS_DEFAULT_PROJECT` is set. |
+| filters | object | No | Optional filters to narrow search results |
+| filters.Repository | string[] | No | Filter by repository names |
+| filters.Path | string[] | No | Filter by file paths |
+| filters.Branch | string[] | No | Filter by branch names |
+| filters.CodeElement | string[] | No | Filter by code element types (function, class, etc.) |
+| top | number | No | Number of results to return (default: 100, max: 1000) |
+| skip | number | No | Number of results to skip for pagination (default: 0) |
+| includeSnippet | boolean | No | Whether to include code snippets in results (default: true) |
+| includeContent | boolean | No | Whether to include full file content in results (default: true) |
+
+### Response
+
+The response includes:
+
+- `count`: The total number of matching files
+- `results`: An array of search results, each containing:
+  - `fileName`: The name of the file
+  - `path`: The path to the file
+  - `content`: The full content of the file (if `includeContent` is true)
+  - `matches`: Information about where the search text was found in the file
+  - `collection`: Information about the collection
+  - `project`: Information about the project
+  - `repository`: Information about the repository
+  - `versions`: Information about the versions of the file
+- `facets`: Aggregated information about the search results, such as counts by repository, path, etc.
+
+### Examples
+
+#### Basic Search
+
+```json
+{
+  "searchText": "function searchCode",
+  "projectId": "MyProject"
+}
+```
+
+#### Using Default Project
+
+```json
+{
+  "searchText": "function searchCode"
+}
+```
+
+#### Search with Filters
+
+```json
+{
+  "searchText": "function searchCode",
+  "projectId": "MyProject",
+  "filters": {
+    "Repository": ["MyRepo"],
+    "Path": ["/src"],
+    "Branch": ["main"],
+    "CodeElement": ["function", "class"]
+  }
+}
+```
+
+#### Search with Pagination
+
+```json
+{
+  "searchText": "function",
+  "projectId": "MyProject",
+  "top": 10,
+  "skip": 20
+}
+```
+
+#### Search without File Content
+
+```json
+{
+  "searchText": "function",
+  "projectId": "MyProject",
+  "includeContent": false
+}
+```
+
+### Notes
+
+- The search is performed using the Azure DevOps Search API, which is separate from the core Azure DevOps API.
+- Azure DevOps Services uses a different base URL (`almsearch.dev.azure.com`) than the regular Azure DevOps API.
+- Azure DevOps Server uses the **same** base URL as the regular Azure DevOps API (your Server collection URL).
+- When `includeContent` is true, the tool makes additional API calls to fetch the full content of each file in the search results.
+- The search API supports a variety of search syntax, including wildcards, exact phrases, and boolean operators. See the [Azure DevOps Search documentation](https://learn.microsoft.com/en-us/azure/devops/project/search/get-started-search?view=azure-devops) for more information.
+- The `CodeElement` filter allows you to filter by code element types such as `function`, `class`, `method`, `property`, `variable`, `comment`, etc.
+- If `projectId` is omitted, the tool uses `AZURE_DEVOPS_DEFAULT_PROJECT` when available.
+
+## search_wiki
+
+The `search_wiki` tool searches wiki pages in Azure DevOps projects.
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| searchText | string | Yes | The text to search for in wiki pages |
+| organizationId | string | No | Optional organization override (defaults to the organization in `AZURE_DEVOPS_ORG_URL`) |
+| projectId | string | No | The project to scope the search to (required for Azure DevOps Server) |
+| filters.Project | string[] | No | Filter by project names |
+| top | number | No | Number of results to return (default: 100, max: 1000) |
+| skip | number | No | Number of results to skip for pagination (default: 0) |
+| includeFacets | boolean | No | Whether to include faceting in results (default: true) |
+
+### Notes
+
+- Azure DevOps Services allows organization-wide wiki search when `projectId` is omitted.
+- Azure DevOps Server requires `projectId`.
+
+## search_work_items
+
+The `search_work_items` tool searches work items across Azure DevOps projects.
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| searchText | string | Yes | The text to search for in work items |
+| organizationId | string | No | Optional organization override (defaults to the organization in `AZURE_DEVOPS_ORG_URL`) |
+| projectId | string | No | The project to scope the search to (required for Azure DevOps Server) |
+| filters.System.TeamProject | string[] | No | Filter by project names |
+| filters.System.WorkItemType | string[] | No | Filter by work item types |
+| filters.System.State | string[] | No | Filter by work item states |
+| filters.System.AssignedTo | string[] | No | Filter by assigned users |
+| filters.System.AreaPath | string[] | No | Filter by area paths |
+| top | number | No | Number of results to return (default: 100, max: 1000) |
+| skip | number | No | Number of results to skip for pagination (default: 0) |
+| includeFacets | boolean | No | Whether to include faceting in results (default: true) |
+| orderBy | array | No | Sort options (field + ASC/DESC) |
+
+### Notes
+
+- Azure DevOps Services allows organization-wide work item search when `projectId` is omitted.
+- Azure DevOps Server requires `projectId`.

package/docs/tools/user-tools.md

@@ -0,0 +1,39 @@
+# Azure DevOps User Tools
+
+This document describes the user-related tools provided by the Azure DevOps MCP server.
+
+## get_me
+
+The `get_me` tool retrieves information about the currently authenticated user.
+
+### Input
+
+This tool doesn't require any input parameters.
+
+```json
+{}
+```
+
+### Output
+
+The tool returns the user's profile information including:
+- `id`: The unique identifier for the user
+- `displayName`: The user's display name
+- `email`: The user's email address
+
+#### Example Response
+
+```json
+{
+  "id": "01234567-89ab-cdef-0123-456789abcdef",
+  "displayName": "John Doe",
+  "email": "john.doe@example.com"
+}
+```
+
+### Error Handling
+
+The tool may return the following errors:
+
+- `AzureDevOpsAuthenticationError`: If authentication fails
+- `AzureDevOpsError`: For general errors when retrieving user information 

package/docs/tools/wiki.md

@@ -0,0 +1,192 @@
+# Azure DevOps Wiki Tools
+
+This document describes the tools available for working with Azure DevOps wikis.
+
+## get_wikis
+
+Lists all wikis in a project or organization.
+
+### Description
+
+The `get_wikis` tool retrieves all wikis available in a specified Azure DevOps project or organization. This is useful for discovering which wikis are available before working with specific wiki pages.
+
+### Parameters
+
+- `organizationId` (optional): The ID or name of the organization. If not provided, the default organization from environment settings will be used.
+- `projectId` (optional): The ID or name of the project. If not provided, the default project from environment settings will be used.
+
+```json
+{
+  "organizationId": "MyOrganization",
+  "projectId": "MyProject"
+}
+```
+
+### Response
+
+The tool returns an array of wiki objects, each containing:
+
+- `id`: The unique identifier of the wiki
+- `name`: The name of the wiki
+- `url`: The URL of the wiki
+- Other wiki properties such as `remoteUrl` and `type`
+
+Example response:
+
+```json
+[
+  {
+    "id": "wiki1-id",
+    "name": "MyWiki",
+    "type": "projectWiki",
+    "url": "https://dev.azure.com/MyOrganization/MyProject/_wiki/wikis/MyWiki",
+    "remoteUrl": "https://dev.azure.com/MyOrganization/MyProject/_git/MyWiki"
+  }
+]
+```
+
+## get_wiki_page
+
+Gets the content of a specific wiki page.
+
+### Description
+
+The `get_wiki_page` tool retrieves the content of a specified wiki page as plain text. This is useful for viewing the content of wiki pages programmatically.
+
+### Parameters
+
+- `organizationId` (optional): The ID or name of the organization. If not provided, the default organization from environment settings will be used.
+- `projectId` (optional): The ID or name of the project. If not provided, the default project from environment settings will be used.
+- `wikiId` (required): The ID or name of the wiki containing the page.
+- `pagePath` (required): The path of the page within the wiki (e.g., "/Home" or "/Folder/Page").
+
+```json
+{
+  "organizationId": "MyOrganization",
+  "projectId": "MyProject",
+  "wikiId": "MyWiki",
+  "pagePath": "/Home"
+}
+```
+
+### Response
+
+The tool returns the content of the wiki page as a string in markdown format.
+
+Example response:
+
+```markdown
+# Welcome to the Wiki
+
+This is the home page of the wiki.
+
+## Getting Started
+
+Here are some links to help you get started:
+- [Documentation](/Documentation)
+- [Tutorials](/Tutorials)
+- [FAQ](/FAQ)
+```
+
+### Error Handling
+
+The tool may throw the following errors:
+
+- `AzureDevOpsResourceNotFoundError`: If the specified wiki or page does not exist
+- `AzureDevOpsPermissionError`: If the authenticated user does not have permission to access the wiki
+- General errors: If other unexpected errors occur during the request
+
+### Example Usage
+
+```typescript
+// Example MCP client call
+const result = await mcpClient.callTool('get_wiki_page', {
+  projectId: 'MyProject',
+  wikiId: 'MyWiki',
+  pagePath: '/Home'
+});
+console.log(result);
+```
+
+### Implementation Details
+
+This tool uses the Azure DevOps REST API to retrieve the wiki page content with the `Accept: text/plain` header to get the content directly in text format. The page path is properly encoded to handle spaces and special characters in the URL.
+
+## list_wiki_pages
+
+Lists all pages within a specified Azure DevOps wiki.
+
+### Description
+
+The `list_wiki_pages` tool retrieves a list of all pages within a specified wiki. It returns summary information for each page, including the page ID, path, URL, and order. This is useful for discovering the structure and contents of a wiki before working with specific pages.
+
+### Parameters
+
+- `organizationId` (optional): The ID or name of the organization. If not provided, the default organization from environment settings will be used.
+- `projectId` (optional): The ID or name of the project. If not provided, the default project from environment settings will be used.
+- `wikiId` (required): The ID or name of the wiki to list pages from.
+
+```json
+{
+  "organizationId": "MyOrganization",
+  "projectId": "MyProject",
+  "wikiId": "MyWiki"
+}
+```
+
+### Response
+
+The tool returns an array of wiki page summary objects, each containing:
+
+- `id`: The unique numeric identifier of the page
+- `path`: The path of the page within the wiki (e.g., "/Home" or "/Folder/Page")
+- `url`: The URL to access the page (optional)
+- `order`: The display order of the page (optional)
+
+Example response:
+
+```json
+[
+  {
+    "id": 1,
+    "path": "/Home",
+    "url": "https://dev.azure.com/MyOrganization/MyProject/_wiki/wikis/MyWiki/1/Home",
+    "order": 0
+  },
+  {
+    "id": 2,
+    "path": "/Documentation",
+    "url": "https://dev.azure.com/MyOrganization/MyProject/_wiki/wikis/MyWiki/2/Documentation",
+    "order": 1
+  },
+  {
+    "id": 3,
+    "path": "/Documentation/Getting-Started",
+    "url": "https://dev.azure.com/MyOrganization/MyProject/_wiki/wikis/MyWiki/3/Getting-Started",
+    "order": 2
+  }
+]
+```
+
+### Error Handling
+
+The tool may throw the following errors:
+
+- `AzureDevOpsResourceNotFoundError`: If the specified wiki does not exist
+- `AzureDevOpsPermissionError`: If the authenticated user does not have permission to access the wiki
+- `AzureDevOpsError`: If other unexpected errors occur during the request
+
+### Example Usage
+
+```typescript
+// Example MCP client call
+const result = await mcpClient.callTool('list_wiki_pages', {
+  projectId: 'MyProject',
+  wikiId: 'MyWiki'
+});
+console.log(result);
+```
+
+### Implementation Details
+
+This tool uses the Azure DevOps REST API to retrieve the list of pages within a wiki. The response is mapped to provide a consistent interface with page ID, path, URL, and order information.