spo-timer-mcp 0.1.0-beta7

SPO Timer MCP Server

🚨 IMPORTANT FOR AI ASSISTANTS 🚨

NEVER call get_timer_job_config_by_name or get_timer_job_definition_by_* tools directly! ALWAYS call the appropriate guide tool FIRST:

• For config questions: get_timer_job_config_guide()
• For complete analysis: get_timer_job_complete_analysis_guide()
• For definition only: get_timer_job_definition_search_guide()

This project implements an MCP server for SharePoint Online (SPO) timer job management and documentation integration. It provides tools to query, summarize, and manage timer job configurations, assignments, priorities, and metadata, as well as fetch and summarize documentation from Azure DevOps wikis.

Features

• Timer Job Configuration: Query and retrieve configuration details for any timer job (e.g., schedule, type, parent, ICM team).
• Timer Job Assignment: Get assignment and ownership information for timer jobs.
• Timer Job Metadata: Access and update metadata for timer jobs, including business justification and operational details.
• Priority and Logic: Query job priority and logic, including integration with Azure DevOps APIs for deeper analysis.
• Wiki Integration: Fetch and summarize timer job documentation from Azure DevOps wikis, including page listing and markdown content extraction.
• Random Number Tool: Utility for generating random numbers for testing and demo purposes.

Usage

You can use this MCP server in VS Code or Visual Studio to:

• Ask questions about timer job configurations (e.g., "get config details for job-migration")
• Summarize timer job documentation from wikis (e.g., "explain Timer Job Configurations from timer wikis")
• Get assignment, priority, and metadata for timer jobs
• Fetch and list all wiki pages under the timer service documentation

Architecture

This MCP server provides a layered architecture for comprehensive timer job analysis with orchestrated workflows and secure Azure DevOps integration.

📖 View Detailed Architecture Documentation

Key Components

• Guide Tools: Orchestration layer providing JSON workflows for systematic analysis
• Config Tools: Timer job configuration analysis from XML sources
• Definition Tools: Source code search with 3-step fallback strategy
• Wiki Tools: Documentation and knowledge base integration
• Azure DevOps Helper: Secure API communication and authentication

Available MCP Tools

Configuration and Documentation Tools

• get_timer_job_config_by_name: Returns configuration details for a specified timer job by job name
• get_timer_job_wiki_summary: Summarizes timer job documentation from the wiki based on a query
• get_random_number: Generates a random number between specified bounds

Timer Job Definition and Logic Tools

• get_timer_job_definition_by_file: STEP 1 - Searches for timer job class files by name (e.g., "MigrationJob.cs") and returns file path and complete content
• get_timer_job_definition_by_class: STEP 2 - Searches for timer job class declarations when file naming doesn't match class naming
• get_timer_job_definition_by_name: STEP 3 - Searches for timer job classes by configured job name (e.g., "job-migration") found in defaultName properties

Timer Job Orchestration Guide Tools

• get_timer_job_definition_search_guide: 🎯 Definition/Logic Only - Use when user asks ONLY for timer job definition, logic details, or how timer job works. Returns actionable JSON instructions for systematic definition search.
• get_timer_job_complete_analysis_guide: 🎯 Complete Analysis - Use when user asks for "all details", "complete information", or "everything about" a timer job. Orchestrates BOTH config AND definition retrieval with smart dual-path workflow.
• get_timer_job_config_guide: 📋 Config Analysis - Use when user asks for timer job configuration details, settings analysis, or wants to understand job properties and conditional logic. Returns structured analysis workflow for configuration interpretation.

Instructions for AI Assistants (Copilot, Claude, etc.)

⚠️ CRITICAL WORKFLOW RULE

❌ NEVER call direct data tools first! ❌

ALWAYS call a guide tool FIRST for user queries about timer jobs. Do NOT call direct data tools (get_timer_job_config_by_name, get_timer_job_definition_by_*) directly unless specifically instructed to do so in the guide workflow.

🚨 COMMON MISTAKE TO AVOID:

• ❌ User: "Get config details for job-migration" → Calling get_timer_job_config_by_name directly
• ✅ User: "Get config details for job-migration" → Call get_timer_job_config_guide() FIRST

🎯 TOOL SELECTION GUIDE: Which Guide Tool to Use

🔍 COMPLETE ANALYSIS (Use get_timer_job_complete_analysis_guide):

• ✅ "Get me all details of job-migration timer job"
• ✅ "Show me everything about SPMigrationJob"
• ✅ "Complete information about [timer job] timer job"
• ✅ "Full analysis of [timer job]"
• ✅ "Get comprehensive details of [job name]"

📋 CONFIG ANALYSIS (Use get_timer_job_config_guide):

• ✅ "Analyze [job] configuration"
• ✅ "Show me [job] settings and properties"
• ✅ "Get the config details of [job] timer job"
• ✅ "Explain [job] configuration and conditional logic"
• ✅ "What are the configuration details for [job]?"
• ✅ "Timer job config analysis for [job]"

🔍 PROPERTY-BASED QUESTIONS (Use get_timer_job_config_guide):

• ✅ "Is my timer job [job-name] enabled?"
• ✅ "Is job-migration running or disabled?"
• ✅ "What schedule does job-blob-packing use?"
• ✅ "When does [job] run next?"
• ✅ "What flights control [job]?"
• ✅ "What kill switches affect [job]?"
• ✅ "Who owns timer job [job-name]?"
• ✅ "What team manages [job]?"
• ✅ "Is [job] in off-peak mode?"
• ✅ "What conditions enable/disable [job]?"
• ✅ "Why is my timer job not running?"
• ✅ "What happens if flight X is activated for [job]?"

🔍 INTERACTIVE STATE DETERMINATION: For property-based questions, the config analysis tool will identify what flights/kill switches affect the property, then request current status from the user to provide a definitive answer. It will NOT assume current flight/kill switch states.

⚙️ CONFIG ONLY (Use get_timer_job_config_by_name):

• ✅ "Get config of job-migration"
• ✅ "Show me timer job configuration for [timer job]"
• ✅ "What are the settings for [job]?"

🔧 DEFINITION/LOGIC ONLY (Use get_timer_job_definition_search_guide):

• ✅ "How does this timer job work?"
• ✅ "Show me the logic for [job]"
• ✅ "Get implementation details of [job]"
• ✅ "What does [job] do in the code?"
• ✅ "Tell me about the job definition of [job] timre job"

🎯 RECOMMENDED WORKFLOWS

For Complete Analysis:

1. FIRST: Call get_timer_job_complete_analysis_guide()
2. FOLLOW: The dual-path workflow (config-first with definition fallback)
3. PRESENT: Combined analysis with both config and implementation details

For Config Analysis:

1. FIRST: Call get_timer_job_config_guide()
2. EXECUTE: The config analysis workflow
3. PRESENT: Comprehensive configuration analysis with conditional logic explanation

For Definition/Logic Only:

1. FIRST: Call get_timer_job_definition_search_guide()
2. EXECUTE: The 3-step definition search workflow
3. PRESENT: Implementation and logic analysis

Example:

User: "Show me everything about job-migration timer job"
✅ RECOMMENDED: get_timer_job_complete_analysis_guide()

User: "Analyze job-blob-packing configuration"
✅ RECOMMENDED: get_timer_job_config_guide()

User: "Is my timer job job-migration enabled?"
✅ RECOMMENDED: get_timer_job_config_guide()

User: "What schedule does job-uber-blob-work-item use?"
✅ RECOMMENDED: get_timer_job_config_guide()

User: "Who owns job-blob-packing?"
✅ RECOMMENDED: get_timer_job_config_guide()

User: "How does SPMigrationJob work?"  
✅ RECOMMENDED: get_timer_job_definition_search_guide()

User: "Get config for job-migration"
✅ RECOMMENDED: get_timer_job_config_guide()

Benefits: Guide tools provide structured JSON workflows, error handling, data extraction logic, and ensure consistent results across all AI assistants.

💡 Why Use Config Analysis Guide for Property Questions?

Config Analysis Guide vs Raw Config Tool:

• ✅ Interprets conditional logic: Explains which flights/kill switches affect properties
• ✅ Determines effective values: Shows actual current state, not just default values
• ✅ Explains reasoning: "Job is enabled BECAUSE flight X is active"
• ✅ Provides operational insights: Next execution time, risk factors, team ownership
• ✅ Handles complex scenarios: Multiple fallback conditions, overlapping logic
• ✅ User-friendly format: Clear status indicators (✅❌⚠️) and structured presentation

Raw Config Tool:

• ❌ Shows raw XML: User must interpret conditional logic themselves
• ❌ No effective value calculation: Shows defaults and conditions separately
• ❌ No operational context: Just configuration data without insights

Example Difference:

User: "Is job-migration enabled?"

Raw Config: Shows IsDisabled=true in DefaultProperties + complex FallbackProperties XML
Config Analysis: "❌ Job is DISABLED because Flight 'EnableMigration' is inactive. 
                 To enable: Activate flight 'EnableMigration' (ID: 12345)"

Timer Job Definition and Logic Tools (MUST USE IN ORDER)

⚠️ CRITICAL: Always follow this exact order for timer job definition searches, unless specifically asked for a certain search type:

1. FIRST: get_timer_job_definition_by_file - Searches for timer job class file (e.g., "MigrationJob.cs") and returns file path and content
2. SECOND: get_timer_job_definition_by_class - Searches for timer job class declaration and returns file path and code snippet (use ONLY if step 1 fails)
3. THIRD: get_timer_job_definition_by_name - Searches for timer job classes by job name (e.g., "job-migration") found in defaultName or displayName properties (use ONLY if steps 1 and 2 fail)

Timer Job Analysis Framework

When presenting timer job results to users, the guide tool's JSON includes comprehensive analysis points. Key areas to focus on:

• Job Purpose & Business Function - What problem does it solve?
• Key Properties - Default name, schedule, priority, SLA
• Implementation Logic - Core execution methods and error handling
• Operational Characteristics - Monitoring, alerts, performance
• Integration Points - External services, database operations, dependencies

The definition-search.json guide provides detailed analysis framework and troubleshooting guidance.

How to Run Locally

1. Build and run the MCP server using dotnet run.
2. Configure your IDE to connect to the MCP server using the provided project path.
3. Use Copilot Chat or MCP tool commands to interact with the server and query timer job information.

Publishing

To publish as a NuGet package:

1. Run dotnet pack -c Release to create the package
2. Push to NuGet.org using your API key

Documentation & Resources

• ModelContextProtocol SDK
• SPO Timer Service Wiki
• List of Timer Jobs
• Use MCP servers in VS Code
• Use MCP servers in Visual Studio

Hackathon Demo

For hackathon scenarios, you can:

• Define deep flows for timer job management and documentation queries
• Demonstrate integration with Azure DevOps REST APIs and wiki documentation
• Show how to answer timer job questions using MCP tools