cascade-mcp copilot-instructions.md

Jira MCP Auth Bridge - AI Agent Instructions

Development Standards

• With all api changes or file changes, keep the documentation in server/readme.md up to date.

Security Guidelines - CRITICAL

NEVER log or expose sensitive credentials:

• ❌ NEVER log RSA private keys (GOOGLE_SERVICE_ACCOUNT_PRIVATE_KEY)
• ❌ NEVER log unencrypted Google service account JSON
• ❌ NEVER log decrypted service account credentials in console output
• ❌ NEVER include private keys or unencrypted credentials in error messages
• ✅ ALWAYS use encrypted credentials (X-Google-Token header with RSA-ENCRYPTED: prefix)
• ✅ ALWAYS decrypt credentials only when needed and never log the decrypted result
• ✅ ONLY log metadata (like client_email or project_id) if absolutely necessary for debugging

Code Organization for MCP Tools

Folder Structure:

• Complex MCP tools should have their own folder under server/providers/{provider}/tools/{tool-name}/
  • Use own folder for: Multi-step workflows, tools with sampling hooks, tools with helper modules
  • Simple single-step tools can remain as single files
• Each tool folder contains:
  • index.ts - Exports the tool registration function
  • {tool-name}.ts - Main tool implementation file
  • {helper-name}.ts - Semi-specific helper modules (parsers, validators, formatters, etc.)

Main Tool File Structure ({tool-name}.ts):

1. Top section: Imports and type definitions
2. Middle section: Tool registration function (orchestration only - calls helper functions)
3. Bottom section: Step helper functions in execution order

Helper Function Guidelines:

• Semi-specific helpers (parsers, validators, domain logic) → Separate module files
  • Example: shell-story-parser.ts with parseShellStoriesFromAdf() and addCompletionMarkerToShellStory() functions
  • Definition: Could be used by different workflows, minimal dependencies on external state/parameters
  • Benefits: Testable, reusable, maintainable
  • Export types/interfaces used across modules
  • Export functions for testing: export function parseShellStoriesFromAdf(...), export function addCompletionMarkerToShellStory(...)
• Broad workflow steps → Exported functions at bottom of main file, in execution order
  • Example: fetchEpicAndExtractShellStories(), findNextUnwrittenStory(), validateDependencies()
  • These orchestrate the tool's main workflow steps
  • Keep main handler clean by delegating to these functions
  • Export for testing: export async function fetchEpicAndExtractShellStories(...)
  • Functions should throw descriptive errors (don't return error objects)