Add optional --project CLI argument to scope MCP server to a specific project

[Meir017]

Summary

Add an optional --project CLI argument that allows users to run the MCP server scoped to a specific Azure DevOps project, rather than just at the organization level. This would serve as a default project for all tools, reducing the need to repeatedly specify the project parameter for each tool invocation.

Motivation

Currently, the MCP server operates at the organization level and every tool that requires project context must have the project specified as a parameter. This creates friction when users primarily work within a single project, as they need to provide the project name/ID for each operation.

Proposed Solution

Add an optional --project CLI parameter that:

• Accepts an Azure DevOps project name or ID
• Serves as a default project for all tools
• Maintains backward compatibility - tools can still accept explicit project parameters that override the default
• Provides clear error messages when project is required but neither default nor explicit parameter is provided

Example Usage

# Current: work at org level, specify project per tool
mcp-server-azuredevops myorg

# Proposed: work at project level by default
mcp-server-azuredevops myorg --project myproject

Implementation Plan

Files to Modify

1. src/index.ts

   • Add --project optional argument via yargs (similar to existing --tenant)
   • Export defaultProject constant (similar to orgName)
   • Pass defaultProject to configureAllTools

2. src/tools.ts

   • Update configureAllTools signature to accept defaultProject?: string
   • Pass defaultProject to all individual tool configuration functions

3. Tool configuration functions in src/tools/*.ts

   • Add defaultProject?: string parameter to each configure*Tools function
   • Make project parameters optional in tool schemas where appropriate
   • Implement fallback logic: const resolvedProject = project || defaultProject
   • Add validation to return helpful errors when project is required but not provided

4. Tests in test/src/tools/*.test.ts

   • Add test cases for default project behavior
   • Verify fallback logic works correctly
   • Ensure backward compatibility with explicit project parameters
   • Test error cases when project is required but not provided

Backward Compatibility

• Fully backward compatible - existing users not providing --project will see no change
• Tools continue to accept explicit project parameters
• When both default and explicit project are provided, explicit takes precedence

Tools Requiring Special Consideration

• Organization-level tools (e.g., core_list_projects) - project should remain optional
• Project-required tools (e.g., work items, pipelines) - should use default when available
• Search tools - currently use orgName directly; consider if project scoping is valuable

Open Questions

1. Should certain tools (e.g., pipelines) require explicit project even when default is configured, or should all tools respect the default pattern?
2. Should search tools be enhanced to accept optional project parameter for scoped searches?
3. Documentation updates needed for README.md and GETTINGSTARTED.md?

Related

This feature would improve the developer experience when working primarily within a single project while maintaining flexibility for cross-project operations.

[danhellem]

This is going to get a bit complicated as just about every tool takes the project as input from the prompt. If you have an idea on how you think it would be implemented without changing current behavior, please create a small PR and we can review. Keep the PR scoped to just a one tool so that we can review implementation.

[Meir017]

My thought here is that if the user passes the project cli argument, then we would modify all of the tools schema to not include the project in them