Skip to content

shrimp-rules.md

Latest commit

 

History

History
278 lines (249 loc) · 20.9 KB

shrimp-rules.md

File metadata and controls

278 lines (249 loc) · 20.9 KB

Development Guidelines for AI Agents - mcp-server-azure-devops

This document is exclusively for AI Agent operational use. DO NOT include general development knowledge.

1. Project Overview

Purpose

  • This project, @tiberriver256/mcp-server-azure-devops, is an MCP (Model Context Protocol) server.
  • Its primary function is to provide tools for interacting with Azure DevOps services.

Technology Stack

  • Core: TypeScript, Node.js
  • Key Libraries:
    • @modelcontextprotocol/sdk: For MCP server and type definitions.
    • azure-devops-node-api: For interacting with Azure DevOps.
    • @azure/identity: For Azure authentication.
    • zod: For schema definition and validation.
    • zod-to-json-schema: For converting Zod schemas to JSON schemas for MCP tools.
  • Testing: Jest (for unit, integration, and e2e tests).
  • Linting/Formatting: ESLint, Prettier.
  • Environment Management: dotenv.

Core Functionality

  • Provides MCP tools to interact with Azure DevOps features including, but not limited to:
    • Organizations
    • Projects (list, get, get details)
    • Repositories (list, get, get content, get tree)
    • Work Items (list, get, create, update, manage links)
    • Pull Requests (list, get, create, update, add/get comments)
    • Pipelines (list, trigger)
    • Search (code, wiki, work items)
    • Users (get current user)
    • Wikis (list, get page, create, update page)

2. Project Architecture

Main Directory Structure

  • ./ (Root):
    • package.json: Project metadata, dependencies, and NPM scripts. REFER to this for available commands and dependencies.
    • tsconfig.json: TypeScript compiler configuration. ADHERE to its settings.
    • .eslintrc.json: ESLint configuration for code linting. ADHERE to its rules.
    • README.md: General project information.
    • setup_env.sh: Shell script for environment setup.
    • CHANGELOG.md (if present): Tracks changes between versions.
  • src/: Contains all TypeScript source code.
    • src/features/: Core application logic. Each subdirectory represents a distinct Azure DevOps feature set (e.g., projects, repositories).
      • src/features/[feature-name]/: Contains all files related to a specific feature.
        • src/features/[feature-name]/index.ts: Main export file for the feature. Exports request handlers (isFeatureRequest, handleFeatureRequest), tool definitions array (featureTools), schemas, types, and individual tool implementation functions. MODIFY this file when adding new tools or functionalities to the feature.
        • src/features/[feature-name]/schemas.ts: Defines Zod input/output schemas for all tools within this feature. DEFINE new schemas here.
        • src/features/[feature-name]/tool-definitions.ts: Defines MCP tools for the feature using @modelcontextprotocol/sdk and zodToJsonSchema. ADD new tool definitions here.
        • src/features/[feature-name]/types.ts: Contains TypeScript type definitions specific to this feature. DEFINE feature-specific types here.
        • src/features/[feature-name]/[tool-name]/: Subdirectory for a specific tool/action within the feature.
          • src/features/[feature-name]/[tool-name]/feature.ts: Implements the core logic for the specific tool (e.g., API calls, data transformation). IMPLEMENT tool logic here.
          • src/features/[feature-name]/[tool-name]/index.ts: Exports the feature.ts logic and potentially tool-specific schemas/types if not in the parent feature files.
          • src/features/[feature-name]/[tool-name]/schema.ts (optional, often re-exports from feature-level schemas.ts): Defines or re-exports Zod schemas for this specific tool.
      • src/features/organizations/, src/features/pipelines/, src/features/projects/, src/features/pull-requests/, src/features/repositories/, src/features/search/, src/features/users/, src/features/wikis/, src/features/work-items/: Existing feature modules. REFER to these for patterns.
    • src/shared/: Contains shared modules and utilities used across features.
      • src/shared/api/: Azure DevOps API client setup (e.g., client.ts).
      • src/shared/auth/: Authentication logic for Azure DevOps (e.g., auth-factory.ts, client-factory.ts). USE these factories; DO NOT implement custom auth.
      • src/shared/config/: Configuration management (e.g., version.ts).
      • src/shared/errors/: Shared error handling classes and utilities (e.g., azure-devops-errors.ts, handle-request-error.ts). USE these for consistent error handling.
      • src/shared/types/: Global TypeScript type definitions (e.g., config.ts, request-handler.ts, tool-definition.ts).
    • src/utils/: General utility functions.
      • src/utils/environment.ts: Provides default values for environment variables (e.g., defaultProject, defaultOrg).
    • src/index.ts: Main application entry point. Handles environment variable loading and server initialization. Exports server components.
    • src/server.ts: MCP server core logic. Initializes the server, registers all tool handlers from features, and sets up request routing. MODIFY this file to register new feature modules (their isFeatureRequest and handleFeatureRequest handlers, and featureTools array).
  • docs/: Currently empty. If documentation is added, MAINTAIN it in sync with code changes.
  • project-management/: Contains project planning and design documents. REFER to architecture-guide.md for high-level design.
  • tests/: Directory for global test setup or utilities if any. Most tests are co-located with source files (e.g., *.spec.unit.ts, *.spec.int.ts, *.spec.e2e.ts).

3. Code Standards

Naming Conventions

  • Files and Directories: USE kebab-case (e.g., my-feature, get-project-details.ts).
  • Variables and Functions: USE camelCase (e.g., projectId, listProjects).
  • Classes, Interfaces, Enums, Types: USE PascalCase (e.g., AzureDevOpsClient, TeamProject, AuthenticationMethod).
  • Test Files:
  • Feature Modules: Place under src/features/[feature-name]/.
  • Tool Logic: Place in src/features/[feature-name]/[tool-name]/feature.ts.
  • Schemas: Define in src/features/[feature-name]/schemas.ts.
  • Tool Definitions (MCP): Define in src/features/[feature-name]/tool-definitions.ts.
  • Types: Feature-specific types in src/features/[feature-name]/types.ts; global types in src/shared/types/.

Formatting

  • Prettier: Enforced via ESLint and lint-staged.
  • Rule: ADHERE to formatting rules defined by Prettier (implicitly via .eslintrc.json which extends prettier).
  • Action: ALWAYS run npm run format (or rely on lint-staged) before committing.

Linting

  • ESLint: Configuration in .eslintrc.json.
  • Rule: ADHERE to linting rules.
  • Action: ALWAYS run npm run lint (or npm run lint:fix) and RESOLVE all errors/warnings before committing.
  • Key Lint Rules (from .eslintrc.json):
    • prettier/prettier: "error" (Prettier violations are ESLint errors).
    • @typescript-eslint/no-explicit-any: "warn" (Avoid any where possible; it's "off" for *.spec.unit.ts and tests/**/*.ts).
    • @typescript-eslint/no-unused-vars: ["error", { "argsIgnorePattern": "^_", "varsIgnorePattern": "^_" }] (No unused variables, allowing _ prefix for ignored ones).

Comments

  • TSDoc: USE TSDoc for documenting public functions, classes, interfaces, and types (e.g., /** ... */).
  • Inline Comments: For complex logic blocks, ADD inline comments (// ...) explaining the purpose.

TypeScript Specifics (from tsconfig.json)

  • strict: true: ADHERE to strict mode.
  • noImplicitAny: true: DO NOT use implicit any. Explicitly type all entities.
  • noUnusedLocals: true, noUnusedParameters: true: ENSURE no unused local variables or parameters.
  • moduleResolution: "Node16": Be aware of Node.js ESM module resolution specifics.
  • paths: { "@/*": ["src/*"] }: USE path alias @/* for imports from src/.

4. Functionality Implementation Standards

Adding a New Tool/Functionality to an Existing Feature

  1. Identify Feature: Determine the relevant feature directory in src/features/[feature-name]/.
  2. Create Tool Directory: Inside the feature directory, CREATE a new subdirectory for your tool, e.g., src/features/[feature-name]/[new-tool-name]/.
  3. Implement Logic: CREATE [new-tool-name]/feature.ts. Implement the core Azure DevOps interaction logic here.
    • USE getClient() from src/shared/api/client.ts or getConnection() from src/server.ts to get WebApi.
    • USE error handling from src/shared/errors/.
  4. Define Schema:
    • ADD Zod schema for the tool's input to src/features/[feature-name]/schemas.ts.
    • EXPORT it.
    • If needed, CREATE [new-tool-name]/schema.ts and re-export the specific schema from the feature-level schemas.ts.
  5. Define MCP Tool:
    • ADD tool definition to src/features/[feature-name]/tool-definitions.ts.
    • Import the Zod schema and use zodToJsonSchema for inputSchema.
    • Ensure name matches the intended tool name for MCP.
  6. Update Feature Index:
    • In src/features/[feature-name]/index.ts:
      • EXPORT your new tool's logic function (from [new-tool-name]/feature.ts or its index.ts).
      • ADD your new tool's name to the includes() check in isFeatureRequest function.
      • ADD a case for your new tool in the handleFeatureRequest function to call your logic. Parse arguments using the Zod schema.
  7. Update Server: No changes usually needed in src/server.ts if the feature module is already registered. The feature's tool-definitions.ts and handleFeatureRequest will be picked up.
  8. Add Tests: CREATE [new-tool-name]/feature.spec.unit.ts and [new-tool-name]/feature.spec.int.ts.

Adding a New Feature Module (e.g., for a new Azure DevOps Service Area)

  1. Create Feature Directory: CREATE src/features/[new-feature-module-name]/.
  2. Implement Tools: Follow "Adding a New Tool" steps above for each tool within this new feature module. This includes creating schemas.ts, tool-definitions.ts, types.ts (if needed), and subdirectories for each tool's feature.ts.
  3. Create Feature Index: CREATE src/features/[new-feature-module-name]/index.ts.
    • EXPORT all schemas, types, tool logic functions.
    • EXPORT the [new-feature-module-name]Tools array from tool-definitions.ts.
    • CREATE and EXPORT is[NewFeatureModuleName]Request (e.g., isMyNewFeatureRequest) type guard.
    • CREATE and EXPORT handle[NewFeatureModuleName]Request (e.g., handleMyNewFeatureRequest) request handler function.
  4. Register Feature in Server:
    • In src/server.ts:
      • IMPORT [new-feature-module-name]Tools, is[NewFeatureModuleName]Request, and handle[NewFeatureModuleName]Request from your new feature's index.ts.
      • ADD ...[new-feature-module-name]Tools to the tools array in the ListToolsRequestSchema handler.
      • ADD an if (is[NewFeatureModuleName]Request(request)) { return await handle[NewFeatureModuleName]Request(connection, request); } block in the CallToolRequestSchema handler.
  5. Add Tests: Ensure comprehensive tests for the new feature module.

5. Framework/Plugin/Third-party Library Usage Standards

  • @modelcontextprotocol/sdk:
    • USE Server class from @modelcontextprotocol/sdk/server/index.js to create the MCP server (src/server.ts).
    • USE StdioServerTransport for transport (src/index.ts).
    • USE schema types like CallToolRequestSchema from @modelcontextprotocol/sdk/types.js.
    • DEFINE tools as ToolDefinition[] (see src/shared/types/tool-definition.ts and feature tool-definitions.ts files).
  • azure-devops-node-api:
    • This is the primary library for Azure DevOps interactions.
    • OBTAIN WebApi connection object via getConnection() from src/server.ts or AzureDevOpsClient from src/shared/auth/client-factory.ts.
    • USE specific APIs from the connection (e.g., connection.getCoreApi(), connection.getWorkItemTrackingApi()).
  • @azure/identity:
    • Used for Azure authentication (e.g., DefaultAzureCredential).
    • Primarily abstracted via AzureDevOpsClient in src/shared/auth/. PREFER using this abstraction.
  • zod:
    • USE for all input/output schema definition and validation.
    • DEFINE schemas in src/features/[feature-name]/schemas.ts.
    • USE z.object({...}), z.string(), z.boolean(), etc.
    • USE .optional(), .default(), .describe() for schema fields.
  • zod-to-json-schema:
    • USE to convert Zod schemas to JSON schemas for MCP inputSchema in tool-definitions.ts.
  • dotenv:
    • Used in src/index.ts to load environment variables from a .env file.
  • Jest:
    • Test files co-located with source files or in feature-specific __test__ directories.
    • Configuration in jest.unit.config.js, jest.int.config.js, jest.e2e.config.js.
  • ESLint/Prettier: See "Code Standards".

6. Workflow Standards

Development Workflow

  1. Branch: CREATE or CHECKOUT a feature/bugfix branch from main (or relevant development branch).
  2. Implement: WRITE code and corresponding tests.
  3. Test:
    • RUN unit tests: npm run test:unit.
    • RUN integration tests: npm run test:int.
    • RUN E2E tests: npm run test:e2e.
    • Or run all tests: npm test.
    • ENSURE all tests pass.
  4. Lint & Format:
    • RUN npm run lint (or npm run lint:fix). RESOLVE all issues.
    • RUN npm run format.
  5. Commit:
    • USE Conventional Commits specification (e.g., feat: ..., fix: ...).
    • RECOMMENDED: Use npm run commit (uses cz-conventional-changelog) for guided commit messages.
  6. Pull Request: PUSH branch and CREATE Pull Request against main (or relevant development branch).

NPM Scripts (from package.json)

  • build: tsc (Compiles TypeScript to dist/).
  • dev: ts-node-dev --respawn --transpile-only src/index.ts (Runs server in development with auto-restart).
  • start: node dist/index.js (Runs compiled server).
  • inspector: npm run build && npx @modelcontextprotocol/inspector node dist/index.js (Runs server with MCP Inspector).
  • test:unit, test:int, test:e2e, test: Run respective test suites.
  • lint, lint:fix: Run ESLint.
  • format: Run Prettier.
  • prepare: husky install (Sets up Git hooks).
  • commit: cz (Interactive commitizen).

CI/CD

  • No explicit CI/CD pipeline configuration files (e.g., azure-pipelines.yml, .github/workflows/) were found in the file listing. If added, REFER to them.

7. Key File Interaction Standards

  • Adding/Modifying a Tool:
    • TOUCH src/features/[feature-name]/[tool-name]/feature.ts (logic).
    • TOUCH src/features/[feature-name]/schemas.ts (Zod schema).
    • TOUCH src/features/[feature-name]/tool-definitions.ts (MCP tool definition).
    • TOUCH src/features/[feature-name]/index.ts (export logic, update request handler and guard).
    • TOUCH corresponding *.spec.unit.ts and *.spec.int.ts files.
  • Adding a New Feature Module:
    • CREATE files within src/features/[new-feature-module-name]/ as per "Functionality Implementation Standards".
    • MODIFY src/server.ts to import and register the new feature module's tools and handlers.
  • Configuration Changes:
    • Environment variables: Managed via .env file (loaded by dotenv in src/index.ts).
    • TypeScript config: tsconfig.json.
    • Linting config: .eslintrc.json.
  • Dependency Management:
    • MODIFY package.json to add/update dependencies.
    • RUN npm install or npm ci.
  • Documentation:
    • docs/ directory is currently empty. If project documentation is added (e.g., docs/feature-x.md), UPDATE it when the corresponding feature src/features/feature-x/ is modified.
    • README.md: UPDATE for significant high-level changes.

8. AI Decision-making Standards

When Adding a New Azure DevOps API Interaction:

  1. Goal: To expose a new Azure DevOps API endpoint as an MCP tool.
  2. Decision: New or Existing Feature?
    • IF the API relates to an existing service area (e.g., adding a new work item query type to work-items feature), MODIFY the existing feature module.
    • ELSE (e.g., interacting with Azure DevOps Audit Logs, a new service area), CREATE a new feature module. (See "Functionality Implementation Standards").
  3. Pattern Adherence:
    • FOLLOW the established pattern:
      • src/features/[feature]/[tool]/feature.ts for logic.
      • src/features/[feature]/schemas.ts for Zod schemas.
      • src/features/[feature]/tool-definitions.ts for MCP tool definitions.
      • src/features/[feature]/index.ts for feature-level exports, request guard (isFeatureRequest), and request handler (handleFeatureRequest).
    • Example: To add get_pipeline_run_logs to pipelines feature:
      • CREATE src/features/pipelines/get-pipeline-run-logs/feature.ts.
      • ADD GetPipelineRunLogsSchema to src/features/pipelines/schemas.ts.
      • ADD get_pipeline_run_logs definition to src/features/pipelines/tool-definitions.ts.
      • UPDATE src/features/pipelines/index.ts to export the new function, add to isPipelinesRequest, and handle in handlePipelinesRequest.
  4. Error Handling:
    • ALWAYS use custom error classes from src/shared/errors/azure-devops-errors.ts (e.g., AzureDevOpsResourceNotFoundError).
    • WRAP external API calls in try/catch blocks.
    • USE handleResponseError from src/shared/errors/handle-request-error.ts in the top-level request handler in src/server.ts (already done for existing features). Feature-specific handlers should re-throw custom errors.
  5. Testing:
    • ALWAYS write unit tests for the new logic in [tool-name]/feature.spec.unit.ts.
    • ALWAYS write integration tests (NEVER mocking anything) in [tool-name]/feature.spec.int.ts. Prefer integration tests over unit tests.

When Modifying Existing Functionality:

  1. Identify Impact: DETERMINE all files affected by the change (logic, schemas, tool definitions, tests, potentially documentation).
  2. Maintain Consistency: ENSURE changes are consistent with existing patterns within that feature module.
  3. Update Tests: MODIFY existing tests or ADD new ones to cover the changes. ENSURE all tests pass.
  4. Version Bumping: For significant changes, consider if a version bump in package.json is warranted (usually handled by release-please).

9. Prohibited Actions

  • DO NOT include general development knowledge or LLM-known facts in this shrimp-rules.md document. This document is for project-specific operational rules for AI.
  • DO NOT explain project functionality in terms of what it does for an end-user. Focus on how to modify or add to it for an AI developer.
  • DO NOT use any type implicitly. tsconfig.json enforces noImplicitAny: true. .eslintrc.json warns on explicit any (@typescript-eslint/no-explicit-any: "warn"), except in unit tests. MINIMIZE explicit any.
  • DO NOT bypass linting (npm run lint) or formatting (npm run format) checks. Code MUST adhere to these standards.
  • DO NOT commit code that fails tests (npm test).
  • DO NOT implement custom Azure DevOps authentication logic. USE the provided AzureDevOpsClient from src/shared/auth/.
  • DO NOT hardcode configuration values (like PATs, Org URLs, Project IDs). These should come from environment variables (see src/index.ts getConfig and src/utils/environment.ts).
  • DO NOT directly call Azure DevOps REST APIs if a corresponding function already exists in the azure-devops-node-api library or in shared project code (e.g., src/shared/api/).
  • DO NOT modify files in dist/ directory directly. This directory is auto-generated by npm run build.
  • DO NOT ignore the project-management/ directory for understanding architectural guidelines, but DO NOT replicate its content here.
  • DO NOT use mocks within integration tests.