{"_id":"@access-mcp/xdmod-metrics","_rev":"4-c3fbf847e6f69ffaf0ea00d5ec072972","name":"@access-mcp/xdmod-metrics","dist-tags":{"latest":"0.4.0"},"versions":{"0.2.3":{"name":"@access-mcp/xdmod-metrics","version":"0.2.3","keywords":["mcp","server","access-ci","xdmod","metrics","analytics","usage"],"author":{"name":"ACCESS-CI"},"license":"MIT","_id":"@access-mcp/xdmod-metrics@0.2.3","maintainers":[{"name":"sweetandfizzy","email":"andrew@sweetandfizzy.com"}],"homepage":"https://github.com/necyberteam/access-mcp/tree/main/packages/xdmod-metrics","bugs":{"url":"https://github.com/necyberteam/access-mcp/issues"},"bin":{"access-xdmod-metrics":"dist/index.js"},"dist":{"shasum":"e7800a367afffd8e41a15690eb757ded5623783e","tarball":"https://registry.npmjs.org/@access-mcp/xdmod-metrics/-/xdmod-metrics-0.2.3.tgz","fileCount":4,"integrity":"sha512-fSLYLFTS0a4UiDP6/o67U/LtDlZL+BBDDRCTBmEPmnmWWWNRAAUSk/eUbJDbIfxNuwynsSeEo8sqjztubIasVQ==","signatures":[{"sig":"MEUCIQDP3yYpwlmB5uNtv9BVETbIkLa8TVGrdyoTQLZeoUjW9AIgMYddxOJ6ngHdRq4GRLGSl2PDP0plr0eWf07elgBCkTs=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":24832},"main":"dist/index.js","type":"module","types":"./dist/index.d.ts","gitHead":"9901f696126bae7dac8984e8bbee0d9574caae9e","scripts":{"dev":"tsc --watch","build":"tsc","start":"node dist/index.js"},"_npmUser":{"name":"sweetandfizzy","email":"andrew@sweetandfizzy.com"},"repository":{"url":"git+https://github.com/necyberteam/access-mcp.git","type":"git","directory":"packages/xdmod-metrics"},"_npmVersion":"11.3.0","description":"MCP server for XDMoD Metrics and Usage Analytics API","directories":{},"_nodeVersion":"24.2.0","dependencies":{"@access-mcp/shared":"^0.2.2"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.0.0","@types/node":"^20.0.0"},"_npmOperationalInternal":{"tmp":"tmp/xdmod-metrics_0.2.3_1754339472999_0.47995443108086877","host":"s3://npm-registry-packages-npm-production"}},"0.3.0":{"name":"@access-mcp/xdmod-metrics","version":"0.3.0","keywords":["mcp","server","access-ci","xdmod","metrics","analytics","usage"],"author":{"name":"ACCESS-CI"},"license":"MIT","_id":"@access-mcp/xdmod-metrics@0.3.0","maintainers":[{"name":"sweetandfizzy","email":"andrew@sweetandfizzy.com"}],"homepage":"https://github.com/necyberteam/access-mcp/tree/main/packages/xdmod-metrics","bugs":{"url":"https://github.com/necyberteam/access-mcp/issues"},"bin":{"access-xdmod-metrics":"dist/index.js"},"dist":{"shasum":"4f6ba11cbc498ec0069e3f3d4b130c4e86b88571","tarball":"https://registry.npmjs.org/@access-mcp/xdmod-metrics/-/xdmod-metrics-0.3.0.tgz","fileCount":6,"integrity":"sha512-sYVJfyV85V4JN2yyoxrp9NG3tUN+rMFEFnzRZMpq9e4IwDBCCCYxCFqrFGA6n3B4Cb3PW0mUT/6I9gi4kDItbQ==","signatures":[{"sig":"MEUCIBKfmcv9v9X8Slj0+tLzWYpcRTblHHfrdE9PpsWou0GtAiEAg6KrhLHm0imcsdBBf6aEjOlX8mHtzN8NoNrseAK0sko=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":59325},"main":"dist/index.js","type":"module","types":"./dist/index.d.ts","gitHead":"f6ce4ddaae1f30d9a4e4017eef80d8a571e6f433","scripts":{"dev":"tsc --watch","build":"tsc","start":"node dist/index.js"},"_npmUser":{"name":"sweetandfizzy","email":"andrew@sweetandfizzy.com"},"repository":{"url":"git+https://github.com/necyberteam/access-mcp.git","type":"git","directory":"packages/xdmod-metrics"},"_npmVersion":"11.3.0","description":"MCP server for XDMoD Metrics and Usage Analytics API","directories":{},"_nodeVersion":"24.2.0","dependencies":{"@access-mcp/shared":"^0.2.2"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.0.0","@types/node":"^20.0.0"},"_npmOperationalInternal":{"tmp":"tmp/xdmod-metrics_0.3.0_1754422939943_0.1165835522633698","host":"s3://npm-registry-packages-npm-production"}},"0.3.1":{"name":"@access-mcp/xdmod-metrics","version":"0.3.1","keywords":["mcp","server","access-ci","xdmod","metrics","analytics","usage"],"author":{"name":"ACCESS-CI"},"license":"MIT","_id":"@access-mcp/xdmod-metrics@0.3.1","maintainers":[{"name":"sweetandfizzy","email":"andrew@sweetandfizzy.com"}],"homepage":"https://github.com/necyberteam/access-mcp/tree/main/packages/xdmod-metrics","bugs":{"url":"https://github.com/necyberteam/access-mcp/issues"},"bin":{"access-xdmod-metrics":"dist/index.js"},"dist":{"shasum":"b80be8792e9b9adfa68ad2bcb5e49b9e3f1f174b","tarball":"https://registry.npmjs.org/@access-mcp/xdmod-metrics/-/xdmod-metrics-0.3.1.tgz","fileCount":6,"integrity":"sha512-4C20IU5FceNprZqK9k8S6o3+yEJT5cGq7PrLP2186Z1BEaU78Y/0dykMy+LlGw9hvyHXAdS/mgtjAzUJK6S5tA==","signatures":[{"sig":"MEYCIQDhCpxqlawR/JUcJQak0SS2T5+Cu3xyS2E/yoTsBc6HqgIhAMLLp7RbfglYl97SHSqaa3pRPy4aRqZA3j+gcqM3BihJ","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":97556},"main":"dist/index.js","type":"module","types":"./dist/index.d.ts","gitHead":"c04f94f2fb0661748de441e6eca1a3e804d1f811","scripts":{"dev":"tsc --watch","build":"tsc","start":"node dist/index.js"},"_npmUser":{"name":"sweetandfizzy","email":"andrew@sweetandfizzy.com"},"repository":{"url":"git+https://github.com/necyberteam/access-mcp.git","type":"git","directory":"packages/xdmod-metrics"},"_npmVersion":"11.3.0","description":"MCP server for XDMoD Metrics and Usage Analytics API","directories":{},"_nodeVersion":"24.2.0","dependencies":{"@access-mcp/shared":"^0.2.3"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.0.0","@types/node":"^20.0.0"},"_npmOperationalInternal":{"tmp":"tmp/xdmod-metrics_0.3.1_1754498087768_0.5363801560526946","host":"s3://npm-registry-packages-npm-production"}},"0.4.0":{"name":"@access-mcp/xdmod-metrics","version":"0.4.0","description":"MCP server for XDMoD Metrics and Usage Analytics API","type":"module","main":"dist/index.js","bin":{"access-xdmod-metrics":"dist/index.js"},"scripts":{"build":"tsc","start":"node dist/index.js","dev":"tsc --watch"},"keywords":["mcp","server","access-ci","xdmod","metrics","analytics","usage"],"author":{"name":"ACCESS-CI"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/necyberteam/access-mcp.git","directory":"packages/xdmod-metrics"},"homepage":"https://github.com/necyberteam/access-mcp/tree/main/packages/xdmod-metrics","bugs":{"url":"https://github.com/necyberteam/access-mcp/issues"},"dependencies":{"@access-mcp/shared":"^0.2.3"},"devDependencies":{"@types/node":"^20.0.0","typescript":"^5.0.0"},"_id":"@access-mcp/xdmod-metrics@0.4.0","gitHead":"6bad40fc2d7e87f269e9a549ba713e59af262a41","types":"./dist/index.d.ts","_nodeVersion":"24.2.0","_npmVersion":"11.3.0","dist":{"integrity":"sha512-cOi2RouAwX8uf19vyOFSDISdAoty5840AZU8bEcnO5gtf+cpKpwxBF7xwiARR2XZAyUEa1PlVvR/YXxjbGVS0w==","shasum":"0fd75284f60a5ec6ff87987f1005f505070bfdf1","tarball":"https://registry.npmjs.org/@access-mcp/xdmod-metrics/-/xdmod-metrics-0.4.0.tgz","fileCount":6,"unpackedSize":97556,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCICokc4y7IMAkTBeZ97JB8HhU5axSlwZ25jVW4h1YGICHAiB/WfX45lGA63uUZeXJM45Px7CQw1a52weG2pNCGU3DHA=="}]},"_npmUser":{"name":"sweetandfizzy","email":"andrew@sweetandfizzy.com"},"directories":{},"maintainers":[{"name":"sweetandfizzy","email":"andrew@sweetandfizzy.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/xdmod-metrics_0.4.0_1755100243901_0.6324911901925838"},"_hasShrinkwrap":false}},"time":{"created":"2025-08-04T20:31:12.822Z","modified":"2025-08-13T15:50:44.265Z","0.2.3":"2025-08-04T20:31:13.189Z","0.3.0":"2025-08-05T19:42:20.121Z","0.3.1":"2025-08-06T16:34:47.933Z","0.4.0":"2025-08-13T15:50:44.087Z"},"bugs":{"url":"https://github.com/necyberteam/access-mcp/issues"},"author":{"name":"ACCESS-CI"},"license":"MIT","homepage":"https://github.com/necyberteam/access-mcp/tree/main/packages/xdmod-metrics","keywords":["mcp","server","access-ci","xdmod","metrics","analytics","usage"],"repository":{"type":"git","url":"git+https://github.com/necyberteam/access-mcp.git","directory":"packages/xdmod-metrics"},"description":"MCP server for XDMoD Metrics and Usage Analytics API","maintainers":[{"name":"sweetandfizzy","email":"andrew@sweetandfizzy.com"}],"readme":"# XDMoD Metrics MCP Server\n\nMCP server providing access to XDMoD (XD Metrics on Demand) Usage Analytics API endpoints for ACCESS-CI infrastructure metrics and statistics, enhanced with NSF Awards integration for comprehensive research funding context.\n\n## API Endpoints Covered\n\n- **Dimensions**: `/controllers/user_interface.php` - Get all available dimensions from Usage Tab\n- **Statistics**: `/controllers/user_interface.php` - Get available statistics for each dimension\n- **Chart Data**: `/controllers/user_interface.php` - Get raw chart data and metadata\n- **Chart Images**: `/controllers/user_interface.php` - Get chart images in SVG, PNG, or PDF format\n- **Chart Links**: Generate direct links to XDMoD portal charts\n- **NSF Awards**: `https://api.nsf.gov/services/v1/awards.json` - NSF award details and search\n- **Debug Tools**: Authentication status and troubleshooting utilities\n\n## Tools\n\n### get_dimensions\n\nGet all available dimensions from the XDMoD Usage Tab.\n\n**Parameters:** None\n\n**Returns:** List of all dimensions with their IDs, categories, and group-by fields.\n\n### get_statistics\n\nGet available statistics for a specific dimension.\n\n**Parameters:**\n\n- `dimension_id` (string): The dimension ID (e.g., \"Jobs_none\")\n- `category` (string): The realm/category (e.g., \"Jobs\")\n- `group_by` (string): The group by field (e.g., \"none\")\n\n**Returns:** List of statistics available for the specified dimension.\n\n### get_chart_data\n\nGet chart data and metadata for a specific statistic.\n\n**Parameters:**\n\n- `realm` (string): The realm (e.g., \"Jobs\")\n- `group_by` (string): The group by field (e.g., \"none\")\n- `statistic` (string): The statistic name (e.g., \"total_cpu_hours\")\n- `start_date` (string): Start date in YYYY-MM-DD format\n- `end_date` (string): End date in YYYY-MM-DD format\n- `dataset_type` (string, optional): Dataset type (default: \"timeseries\")\n\n**Returns:** Raw chart data including descriptions and metadata.\n\n### get_chart_image\n\nGet chart image (SVG, PNG, or PDF) for a specific statistic.\n\n**Parameters:**\n\n- `realm` (string): The realm (e.g., \"Jobs\")\n- `group_by` (string): The group by field (e.g., \"none\")\n- `statistic` (string): The statistic name (e.g., \"total_cpu_hours\")\n- `start_date` (string): Start date in YYYY-MM-DD format\n- `end_date` (string): End date in YYYY-MM-DD format\n- `format` (string, optional): Image format - \"svg\", \"png\", or \"pdf\" (default: \"svg\"). Note: PNG displays directly in Claude Desktop, SVG returns as data URL and code, PDF returns as downloadable data\n- `width` (number, optional): Image width in pixels (default: 916)\n- `height` (number, optional): Image height in pixels (default: 484)\n- `dataset_type` (string, optional): Dataset type (default: \"timeseries\")\n\n**Returns:** Chart image data in the requested format.\n\n### get_chart_link\n\nGenerate a direct link to view the chart in the XDMoD portal.\n\n**Parameters:**\n\n- `realm` (string): The realm (e.g., \"Jobs\", \"SUPREMM\")\n- `group_by` (string): The group by field (e.g., \"none\", \"resource\")\n- `statistic` (string): The statistic name (e.g., \"total_cpu_hours\", \"gpu_time\")\n\n**Returns:** Direct URL to view the interactive chart in XDMoD. Use the portal's filtering options to narrow down to specific resources, users, or other criteria.\n\n### get_nsf_award\n\nGet NSF award details for a specific award number.\n\n**Parameters:**\n\n- `award_number` (string): NSF award number (e.g., '2138259')\n\n### find_nsf_awards_by_pi\n\nFind NSF awards for a specific Principal Investigator.\n\n**Parameters:**\n\n- `pi_name` (string): Principal Investigator name to search for\n- `limit` (number, optional): Maximum number of awards to return (default: 10)\n\n### find_nsf_awards_by_personnel\n\nSearch NSF awards by Principal Investigator name.\n\n**Note:** Co-PI and Program Officer searches are not reliable in the NSF API and have been removed.\n\n**Parameters:**\n\n- `person_name` (string): Principal Investigator name to search for\n- `limit` (number, optional): Maximum number of awards to return (default: 10)\n\n### get_usage_with_nsf_context\n\nGet XDMoD usage data enriched with NSF funding context for a researcher or institution.\n\n**Parameters:**\n\n- `researcher_name` (string, optional): Name of researcher to analyze\n- `institution_name` (string, optional): Institution to analyze\n- `start_date` (string): Start date in YYYY-MM-DD format\n- `end_date` (string): End date in YYYY-MM-DD format\n- `limit` (number, optional): Maximum NSF awards to include (default: 10)\n\n**Returns:** Combined analysis including XDMoD usage metrics and associated NSF funding portfolio\n\n### analyze_funding_vs_usage\n\nCompare NSF funding amounts with actual XDMoD computational usage patterns.\n\n**Parameters:**\n\n- `nsf_award_number` (string): Specific NSF award number to analyze\n- `start_date` (string): Start date in YYYY-MM-DD format  \n- `end_date` (string): End date in YYYY-MM-DD format\n\n**Returns:** Comparative analysis of funding allocation versus computational resource consumption\n\n### institutional_research_profile\n\nGenerate a comprehensive research profile combining XDMoD usage patterns with NSF funding for an institution.\n\n**Parameters:**\n\n- `institution_name` (string): Institution name to profile\n- `start_date` (string): Start date in YYYY-MM-DD format\n- `end_date` (string): End date in YYYY-MM-DD format\n- `limit` (number, optional): Maximum NSF awards to include (default: 20)\n\n**Returns:** Comprehensive institutional profile with funding and usage correlation analysis\n\n### debug_auth_status\n\nCheck authentication status and debug information.\n\n**Parameters:** None\n\n**Returns:** Comprehensive debugging information including:\n- API token status and configuration\n- Available tools and their authentication requirements  \n- Troubleshooting guidance for authentication issues\n- Environment variable and command-line argument detection\n\n## Authentication\n\nThe server supports optional API token authentication via the `XDMOD_API_TOKEN` environment variable. While authenticated access is configured, the current release focuses on public data access. Personal usage features are in development and preserved in `src/user-specific.ts` for future releases.\n\n## Quick Start with Claude Desktop\n\nAfter adding this server to your Claude Desktop configuration, you can ask natural language questions like:\n\n### 🔍 **Explore Available Metrics**\n\n- \"What dimensions are available in XDMoD?\"\n- \"Show me all statistics for the Jobs dimension\"\n- \"What metrics can I track for Cloud resources?\"\n\n### 📊 **Get Usage Data**\n\n- \"Show me total CPU hours for January 2024\"\n- \"What was the job count last month?\"\n- \"Get me the average wait time data for Q1 2024\"\n\n### 📈 **Generate Charts**\n\n- \"Create an SVG chart of CPU hours for the last 30 days\"\n- \"Generate a high-resolution PNG chart of job counts for March 2024\"\n- \"Show me a PDF chart of resource utilization trends\"\n\n### 🔗 **Portal Integration**\n\n- \"Give me a direct link to the CPU hours chart in XDMoD\"\n- \"Generate a link to view GPU usage by resource in the portal\"\n- \"How can I view this data interactively in the portal?\"\n\n### 🔬 **NSF Integration & Research Analysis**\n\n- \"Show me Dr. Smith's computational usage with their NSF funding context\"\n- \"Analyze how NSF award 2138259's funding correlates with actual usage\"\n- \"Generate a research profile for University of Illinois combining usage and NSF funding\"\n- \"Compare funding allocation versus computational resource consumption\"\n\n## Detailed Usage Examples\n\n### Getting Available Dimensions\n\n**Natural Language**: \"What metrics are available in XDMoD?\"\n\n**Tool Call**:\n\n```typescript\nconst dimensions = await get_dimensions();\n```\n\n**Returns**: List of dimensions like Jobs, Cloud, Storage, GPU, etc.\n\n### Getting Statistics for a Dimension\n\n**Natural Language**: \"Show me what statistics I can get for Jobs\"\n\n**Tool Call**:\n\n```typescript\nconst statistics = await get_statistics({\n  dimension_id: \"Jobs_none\",\n  category: \"Jobs\",\n  group_by: \"none\",\n});\n```\n\n**Returns**: Metrics like total_cpu_hours, job_count, avg_cpu_hours, wait_time, etc.\n\n### Getting Chart Data\n\n**Natural Language**: \"Get me CPU hours data for January 2024\"\n\n**Tool Call**:\n\n```typescript\nconst chartData = await get_chart_data({\n  realm: \"Jobs\",\n  group_by: \"none\",\n  statistic: \"total_cpu_hours\",\n  start_date: \"2024-01-01\",\n  end_date: \"2024-01-31\",\n});\n```\n\n**Returns**: Raw data with chart descriptions and metadata\n\n### Getting GPU Usage Data\n\n**Natural Language**: \"Show me GPU usage on Bridges 2 for the last year\"\n\n**Tool Call**:\n\n```typescript\nconst gpuData = await get_chart_data({\n  realm: \"SUPREMM\",  // Use SUPREMM for GPU metrics!\n  group_by: \"resource\",\n  statistic: \"gpu_time\", // or \"avg_percent_gpu_usage\"\n  start_date: \"2024-01-01\",\n  end_date: \"2024-12-31\",\n  filters: {\n    resource: \"Bridges 2 GPU\"\n  }\n});\n```\n\n### Getting Chart Images\n\n**Natural Language**: \"Create a chart showing CPU usage trends for Q1 2024\"\n\n**Tool Call**:\n\n```typescript\n// SVG format (default)\nconst svgChart = await get_chart_image({\n  realm: \"Jobs\",\n  group_by: \"none\",\n  statistic: \"total_cpu_hours\",\n  start_date: \"2024-01-01\",\n  end_date: \"2024-03-31\",\n  format: \"svg\",\n});\n\n// High-resolution PNG\nconst pngChart = await get_chart_image({\n  realm: \"Jobs\",\n  group_by: \"none\",\n  statistic: \"total_cpu_hours\",\n  start_date: \"2024-01-01\",\n  end_date: \"2024-03-31\",\n  format: \"png\",\n  width: 1920,\n  height: 1080,\n});\n```\n\n### Getting Chart Links\n\n**Natural Language**: \"Give me a link to view this chart in XDMoD\"\n\n**Tool Call**:\n\n```typescript\n// Basic chart link\nconst chartLink = await get_chart_link({\n  realm: \"Jobs\",\n  group_by: \"none\",\n  statistic: \"total_cpu_hours\"\n});\n\n// GPU usage chart link grouped by resource\nconst gpuChartLink = await get_chart_link({\n  realm: \"SUPREMM\",\n  group_by: \"resource\", \n  statistic: \"gpu_time\"\n});\n```\n\n**Returns**: Direct URL like: `https://xdmod.access-ci.org/index.php#tg_usage?node=statistic&realm=Jobs&group_by=none&statistic=total_cpu_hours`\n\n### Research Analysis with NSF Integration\n\n**Natural Language**: \"Analyze Dr. Smith's computational usage with their NSF funding context for 2024\"\n\n**Tool Call**:\n\n```typescript\nconst researchAnalysis = await get_usage_with_nsf_context({\n  researcher_name: \"John Smith\",\n  start_date: \"2024-01-01\",\n  end_date: \"2024-12-31\",\n  limit: 5\n});\n```\n\n**Returns**: Combined analysis showing XDMoD usage patterns alongside NSF funding portfolio\n\n### Funding vs Usage Analysis\n\n**Natural Language**: \"Compare NSF award 2138259's funding with actual computational usage\"\n\n**Tool Call**:\n\n```typescript\nconst fundingAnalysis = await analyze_funding_vs_usage({\n  nsf_award_number: \"2138259\",\n  start_date: \"2024-01-01\",\n  end_date: \"2024-12-31\"\n});\n```\n\n**Returns**: Detailed comparison of funding allocation versus actual resource consumption\n\n### Institutional Research Profile\n\n**Natural Language**: \"Generate a comprehensive research profile for University of Illinois\"\n\n**Tool Call**:\n\n```typescript\nconst institutionProfile = await institutional_research_profile({\n  institution_name: \"University of Illinois\",\n  start_date: \"2024-01-01\", \n  end_date: \"2024-12-31\",\n  limit: 15\n});\n```\n\n**Returns**: Complete institutional analysis combining usage patterns with NSF funding landscape\n\n## Understanding Realms\n\nXDMoD organizes metrics into different **realms** that provide different types of data:\n\n### **Jobs Realm** \nBasic job accounting and resource usage metrics:\n- `total_cpu_hours` - Total CPU Hours\n- `job_count` - Number of Jobs Ended\n- `avg_cpu_hours` - Average CPU Hours per Job\n- `total_waitduration_hours` - Total Wait Duration Hours\n- `avg_waitduration_hours` - Average Wait Duration Hours\n- `max_processors` - Maximum Processor Count\n- `total_ace` - ACCESS Credit Equivalents Charged: Total\n- `utilization` - ACCESS CPU Utilization\n\n### **SUPREMM Realm** \nDetailed performance analytics and system metrics:\n- `gpu_time` - **GPU Hours: Total** 🎯\n- `avg_percent_gpu_usage` - **Avg GPU usage: weighted by GPU hour** 🎯\n- `wall_time` - CPU Hours: Total\n- `cpu_time_user` - CPU Hours: User: Total\n- `avg_percent_cpu_user` - Avg CPU %: User: weighted by core-hour\n- `avg_flops_per_core` - Avg: FLOPS: Per Core weighted by core-hour\n- `avg_memory_per_core` - Avg: Memory: Per Core weighted by core-hour\n- `avg_ib_rx_bytes` - Avg: InfiniBand rate: Per Node weighted by node-hour\n\n**💡 For GPU metrics, always use the SUPREMM realm!**\n\n## Authentication \n\nThe server supports optional API token authentication for enhanced debugging and troubleshooting. The current release focuses on system-wide public metrics data from XDMoD.\n\n## Practical Workflows\n\n### 📊 **Monthly Reporting Workflow**\n\n1. \"What dimensions are available?\" → Choose your metric category\n2. \"Show me statistics for Jobs dimension\" → Pick relevant metrics\n3. \"Generate a chart of total CPU hours for last month\" → Get visual\n4. \"Give me the link to view this in XDMoD\" → Share with team\n\n### 🔍 **Performance Investigation**\n\n1. \"Get me job count data for the past week\"\n2. \"Show me average wait times for the same period\"\n3. \"Create a comparison chart of wait times vs job counts\"\n4. \"What's the correlation between usage and wait times?\"\n\n### 📈 **Capacity Planning**\n\n1. \"Show CPU usage trends for the last 6 months\"\n2. \"What are the peak usage periods?\"\n3. \"Generate high-resolution charts for presentation\"\n4. \"Export data for further analysis\"\n\n### 🔬 **Research Impact Analysis**\n\n1. \"Analyze Dr. Johnson's computational usage with NSF funding context\"\n2. \"Compare funding efficiency across different research groups\"\n3. \"Generate institutional research profile with funding correlations\"\n4. \"Identify usage patterns that correlate with successful funding outcomes\"\n\n## Date Formats and Ranges\n\nAll date parameters must be in `YYYY-MM-DD` format:\n\n- `2024-01-01` - January 1st, 2024\n- `2024-12-31` - December 31st, 2024\n\n**Common Date Ranges**:\n\n- Last Month: Use first and last day of previous month\n- Quarter: Q1 = Jan 1 - Mar 31, Q2 = Apr 1 - Jun 30, etc.\n- Year to Date: Jan 1 to today's date\n- Custom Period: Any start and end date you need\n\n## Tips and Best Practices\n\n### 🎯 **Getting Started**\n\n1. Always start by exploring available dimensions\n2. Check what statistics are available for your chosen dimension\n3. Use descriptive natural language - Claude will map it to the right tools\n\n### 📊 **Working with Data**\n\n- Request data first to understand the structure\n- Then generate visualizations based on what you find\n- Use chart links to share interactive views with colleagues\n\n### 🖼️ **Chart Formats**\n\n- **SVG**: Best for web display and scaling\n- **PNG**: Best for presentations and documents\n- **PDF**: Best for archival and printing\n\n### 🔄 **Efficient Workflows**\n\n- Save frequently used date ranges\n- Bookmark generated portal links\n- Export data for longitudinal analysis\n\n## Authentication\n\n### **Public Access (Default)**\nBy default, this server uses public access to XDMoD APIs and provides general usage statistics and metrics.\n\n### **Authenticated Access (Personal Data)**\nFor access to personal usage data like \"show me my credit usage in the last 3 months\", you can set up authentication using an XDMoD API token.\n\n#### **Setting Up Authentication:**\n\n1. **Generate API Token:**\n   - Sign in to [XDMoD portal](https://xdmod.access-ci.org/)\n   - Click \"My Profile\" button (top-right corner)\n   - Click \"API Token\" tab\n   - Copy your token (save it securely - you won't see it again!)\n\n2. **Configure Authentication (Choose One):**\n\n   **Option A: Environment Variable**\n   ```bash\n   export XDMOD_API_TOKEN=\"your-token-here\"\n   npm start\n   ```\n\n   **Option B: Claude Desktop Config** *(Recommended)*\n   ```json\n   {\n     \"mcpServers\": {\n       \"xdmod-metrics\": {\n         \"command\": \"node\",\n         \"args\": [\n           \"/path/to/access_mcp/packages/xdmod-metrics/dist/index.js\",\n           \"--api-token\",\n           \"your-token-here\"\n         ]\n       }\n     }\n   }\n   ```\n\n3. **Test Authentication:**\n   Ask Claude: *\"Debug my XDMoD authentication status\"* to verify setup\n\n#### **Authentication Features:**\nWhen authenticated, you get enhanced debugging capabilities:\n\n- `debug_auth_status` - Comprehensive authentication status and troubleshooting\n\n#### **Example Authentication Queries:**\n- \"Debug my XDMoD authentication status\"\n- \"Check if my API token is working\"\n- \"Help me troubleshoot authentication issues\"\n\n**Note:** Personal usage data features are in development. The current release focuses on system-wide public metrics.\n\n## Data Source\n\nAll data is sourced from the ACCESS-CI XDMoD portal at https://xdmod.access-ci.org/\n\n## Usage\n\n```bash\n# Install and build\nnpm install\nnpm run build\n\n# Start the server\nnpm start\n```\n\nThe server runs on stdio transport and can be integrated with MCP-compatible clients.\n","readmeFilename":"README.md"}