MedRecPro MCP Server

MedRecPro

MedRecPro is a pharmaceutical structured product label (SPL) management platform built with ASP.NET Core. It provides secure access to FDA drug label data through a RESTful API, an AI-powered chat interface, a Model Context Protocol (MCP) server for integration with AI assistants like Claude, and an interactive adverse-event risk dashboard built on a multi-stage table-standardization and risk-statistics pipeline.

Specifications

• HL7 Version: HL7 Dec 2023 https://www.fda.gov/media/84201/download
• Info: https://www.fda.gov/industry/fda-data-standards-advisory-board/structured-product-labeling-resources
• SPL Data Source: https://dailymed.nlm.nih.gov/dailymed/spl-resources-all-drug-labels.cfm
• Orange Book Data Source: https://www.fda.gov/drugs/drug-approvals-and-databases/approved-drug-products-therapeutic-equivalence-evaluations-orange-book

Technology Stack

• Runtime: ASP.NET Core (.NET 8.0 LTS)
• Database: Azure SQL Server (Serverless free tier) with Dapper + Entity Framework Core
• Authentication: Cookie-based auth with Google and Microsoft OAuth providers; JWT bearer tokens for API access; McpBearer JWT scheme for MCP server integration (claims normalized to standard JWT short names: sub, name, email)
• AI Integration: Claude API for natural language query interpretation and synthesis
• MCP Protocol: Model Context Protocol server with OAuth 2.1 (PKCE S256) for Claude.ai connector integration
• Hosting: Azure App Service (Windows, IIS) with Cloudflare CDN/WAF/DNS
• Secrets: Azure Key Vault
• API Documentation: Swagger/OpenAPI
• Error Contracts: Centralized ASP.NET Core IExceptionHandler with sanitized RFC 7807 ProblemDetails responses and request trace correlation
• Testing: MSTest, WebApplicationFactory<Program>, kept-open SQLite test databases, reviewed Debug/Release OpenAPI snapshots, and real-host HTTP contracts
• Verification: PowerShell gate runner plus GitHub Actions for fast architecture checks, Debug/Release contracts, and the full regression suite
• SPL Rendering: RazorLight templates for SPL XML-to-HTML generation

Solution Architecture

The solution's three web projects are deployed to a single Azure App Service using IIS virtual applications (the console, library, React SPA source, prototypes, and test projects are not deployed as separate apps):

                        Cloudflare (CDN/WAF/DNS)
                                |
                                v
    Azure App Service: "MedRecPro" (Windows, IIS)
   +--------------------------------------------------------+
   |                                                        |
   |  /                site\wwwroot       MedRecProStatic   |
   |  /adverse-events  (MedRecProStatic, React island)      |
   |  /api             site\wwwroot\api   MedRecPro API     |
   |  /mcp             site\wwwroot\mcp   MedRecProMCP      |
   |                                                        |
   +--------------------------------------------------------+
                        |
                        v
               Azure Key Vault
              (medrecprovault)

Build and Solution Boundary

MedRecPro.sln is the focused API/import/test solution. It intentionally contains MedRecPro, MedRecProImportClass, and MedRecProTest; the test project references MedRecProConsole, so the CLI stays in the regular regression build without making the solution responsible for every deployed app. MedRecProStatic and MedRecProMCP are separately deployed IIS virtual applications and should be built or published explicitly when their code changes:

dotnet build .\MedRecPro.sln --no-restore -p:UseAppHost=false
dotnet build .\MedRecProStatic\MedRecProStatic.csproj --no-restore -p:UseAppHost=false
dotnet build .\MedRecProMCP\MedRecProMCP.csproj --no-restore -p:UseAppHost=false

If a local apphost executable is locked by a running process, keep output inside the workspace and disable apphost generation for the verification pass, for example dotnet build .\MedRecPro.sln --no-restore -p:UseAppHost=false -p:BaseOutputPath=.\MedRecPro\.codex-build\. The API project excludes bin/** and .codex-build/** from default item globbing so copied RazorLight templates from generated output cannot re-enter compilation when BaseOutputPath is redirected.

How the Projects Relate

MedRecProStatic is the user-facing front end. Its AI chat interface (/Home/Chat) communicates with the API using a request-interpret-execute-synthesize pattern: user queries are sent to the API's AI endpoints, which use Claude to map natural language to API calls. The static site also serves OAuth/MCP discovery metadata (/.well-known/*) at the domain root on behalf of the MCP server, because the MCP SDK resolves discovery URLs relative to the domain root rather than the /mcp path.

MedRecPro (API) is the core backend. It handles label data CRUD, user authentication, AI query interpretation via Claude, database views for navigation, SPL document rendering via RazorLight templates, and the HTTP/progress boundary for SPL ZIP uploads. The public Label surface remains one 51-operation /api/Label route family, but its implementation is split across small feature controllers and injected query/operation services. The former DtoLabelAccess implementation is now owned by those services; one forwarding-only static facade remains for external .NET compatibility. The actual SPL ZIP traversal, XML parsing, duplicate checks, and parser orchestration live in MedRecProImportClass; the API keeps thin compatibility adapters and maps import-library result DTOs back into the web import-progress models.

MedRecProMCP is an OAuth 2.1 gateway that exposes MedRecPro API capabilities as MCP tools. When Claude.ai connects, it authenticates users through Google/Microsoft OAuth, resolves upstream identity provider identities to numeric database user IDs (auto-provisioning new users if needed), then forwards authenticated MCP JWTs to the MedRecPro API. It uses JWT tokens, PKCE (S256), Dynamic Client Registration (RFC 7591), and a shared PKSecret for encrypted user ID exchange with the API.

MedRecProReact is the source for the adverse-event risk dashboard — a React + Vite single-page "island". Its Vite build emits a deterministic bundle directly into MedRecProStatic/wwwroot/ae-dashboard, which MedRecProStatic serves at /adverse-events. The dashboard reads only from the API's /api/AdverseEvent surface (AdverseEventController), which in turn queries the materialized AE risk tables produced by the table-standardization pipeline (Stage 5). Current dashboard focuses cover product-level risk, pharmacologic-class SOC correlation, and MedDRA-system-scoped class correlation. See the MedRecProReact README for the dashboard, and the MedRecProImportClass README for the risk-statistics contract.

Backend Boundaries and Compatibility Safeguards

Repository File Structure

The tree below is intentionally curated around deployable projects and the current architecture/verification boundaries. Every named path was checked against the live repository on 2026-07-14.

./
  README.md
  MedRecPro.sln                     # Focused API/import/test solution
  .github/
    workflows/
      medrecpro-verification.yml    # Fast + Debug/Release contract + full CI gates
  scripts/
    Invoke-MedRecProVerification.ps1

  MedRecPro/                        # ASP.NET Core Web API
    Program.cs                      # Ordered composition and middleware shell
    MedRecPro.csproj                # Excludes bin/** and .codex-build/** from source discovery
    Configuration/
      DatabaseSecurityOptions.cs
      MedRecProApplicationServiceExtensions.cs
      MedRecProAuthenticationExtensions.cs
      MedRecProMiddlewareExtensions.cs
      MedRecProMvcExtensions.cs
      MedRecProStartupDiagnosticsExtensions.cs
      MedRecProSwaggerExtensions.cs
    Controllers/
      ApiControllerBase.cs          # Debug api/[controller] vs Release [controller]
      LabelController.cs            # Empty compatibility shell
      LabelSearchController.cs      # Empty compatibility shell
      LabelApplicationController.cs
      LabelClassificationController.cs
      LabelComparisonController.cs
      LabelDocumentController.cs
      LabelImportController.cs
      LabelIngredientController.cs
      LabelMarkdownController.cs
      LabelMetadataController.cs
      LabelProductIdentifierController.cs
      LabelProductSearchController.cs
      LabelSectionController.cs
      LabelSectionNavigationController.cs
      FeatureControllerNameAttribute.cs
      SwaggerGroupAttribute.cs
      AdverseEventController.cs
      AiController.cs
      AuthController.cs
      OrangeBookController.cs
      SettingsController.cs
      UsersController.cs
    Service/
      AeDashboardServices.cs        # Injected AE dashboard use-case services and policies
      AppCacheService.cs            # IAppCache and user-context seams
      PrimaryKeyCipher.cs           # IPrimaryKeyCipher encryption boundary
      ClaudeSkillNameMapper.cs
      SplImportService.cs           # Web compatibility adapter over the import library
      SplParsingService.cs          # Legacy parser adapter over the import library
      Common/
        ActivityLogDispatcher.cs    # Channel dispatcher + scoped hosted consumer
      Label/
        ComparisonJobCoordinator.cs
        CompleteLabelService.cs
        LabelAiSearchService.cs
        LabelQueryServiceContracts.cs
        LabelQueryServices.cs
        LabelSectionCrudService.cs
        LabelXmlDocumentService.cs
        Common/
          LabelQueryCachePolicy.cs
          LegacyDtoLabelCacheKeyBuilder.cs
        Implementation/
          LabelQueryDataAccess.cs
          LabelQueryDataAccess-BatchLoaders.cs
          LabelQueryDataAccess-Document.cs
          LabelQueryDataAccess-Views.cs
          LabelQueryLegacyCompatibility.cs
    DataAccess/
      DtoLabelAccess.Compatibility.cs   # Forwarding-only 57-name/58-overload facade
      DtoLabelAccess-AeDashboard.cs     # AeDashboardDataAccess query implementation
      AeDashboardFavoriteAccess.cs
      AeDashboardDerivation.cs
      AeCorrelationPipelineModels.cs
      RepositoryDataAccess.cs
      UserDataAccess.cs
    Features/
      AeDashboard/
        Mapping/
          AeDashboardDtoMapper.cs
        Models/
          AeDashboardDto.cs
        Persistence/
          AeDashboardModelConfigurations.cs
      Label/
        Mapping/
          LabelDocumentAssembler.cs
    Exceptions/
      AuthorizationExceptions.cs
      MedRecProExceptionHandler.cs
      RequestCorrelation.cs
    Filters/
      ActivityLogActionFilter.cs
      RequireActorAttributeFilter.cs
      RequireUserRoleAttributeFilter.cs
    Mappers/
      ImportResultMapper.cs
    Models/
      ImportStatus.cs               # Web/import operation-status boundary
    Middleware/
      TarpitMiddleware.cs
    Skills/
      skills.md                     # Capability contracts
      selectors.md                  # Skill routing rules
      interfaces/                   # API and response mappings
    Views/
      SplTemplates/                 # RazorLight SPL templates
      Stylesheets/
    SQL/                            # Schema, views, indexes, import/export, AE materialization
    docs/
      logging-conventions.md
      verification-gates.md

  MedRecProImportClass/             # Shared SPL/Orange Book import and analytics library
    Models/
      Import.cs
      ImportStatus.cs
      OrangeBook.cs
    DataAccess/
      RepositoryDataAccess.cs
      UserDataAccess.cs
    Service/
      SplImportService.cs
      SplParsingService.cs
      SplDataService.cs
      ParsingServices/              # SPL and Orange Book parsers
      ParsingValidators/
      TransformationServices/
        TableStandardizationServiceCollectionExtensions.cs
        ClaudeCorrectionPayloadBuilder.cs
        BaseTableFlattening/
          ColumnStandardizationService.cs
        AdverseEventTableFlattening/
    TableStandards/
      normalization-rules.md
      column-contracts.md
      table-types.md
    Context/
      ApplicationDbContext.cs

  MedRecProConsole/                 # Bulk SPL/Orange Book import CLI
    Program.cs
    Services/
      ImportService.cs
      ImportProgressTracker.cs
      OrangeBookImportService.cs
    Models/
    Helpers/

  MedRecProStatic/                  # Static site, AI chat, and dashboard host
    Program.cs
    Controllers/
      HomeController.cs
      AdverseEventDashboardController.cs
    Views/
      Home/
      AdverseEventDashboard/
      Shared/
    wwwroot/
      ae-dashboard/                 # Committed MedRecProReact build
      js/
        chat/

  MedRecProReact/                   # React + Vite adverse-event dashboard source
    package.json
    vite.config.js
    src/
      App.jsx
      api/
      components/
      hooks/
      lib/
      test/

  MedRecProMCP/                     # OAuth 2.1 MCP gateway
    Program.cs
    Endpoints/
      OAuthEndpoints.cs
      OAuthMetadataEndpoints.cs
    Services/
    Tools/
      DrugLabelTools.cs
      UserTools.cs

  MedRecProPrototypes/              # Standalone UI prototypes

  MedRecProTest/                    # MSTest unit, relational, host, and contract suite
    MedRecProTest.csproj
    TestInfrastructure/
      MedRecProTestConfiguration.cs
      MedRecProWebApplicationFactory.cs
      MedRecProHostFixture.cs
      TestAuthenticationHandler.cs
      TestExceptionThrowingStartupFilter.cs
      CountingDbCommandInterceptor.cs
      ControllerArchitectureTests.cs
      LoggingAndErrorHandlingArchitectureTests.cs
      ReflectionUsageArchitectureTests.cs
      TestProjectDependencyGuardTests.cs
    Contracts/
      LabelOpenApiContractTests.cs
    Integration/
      LabelHttpContractTests.cs
      StartupSmokeTests.cs
    TestData/
      OpenApi/
        label-debug.contract.json
        label-release.contract.json
    ColumnStandardizationServiceTests.cs   # Thin shared-fixture shell
    ColumnStandardizationTestFixture.cs
    ColumnStandardization/
      ColumnStandardizationCleanupTests.cs
      ColumnStandardizationColumnContractTests.cs
      ColumnStandardizationInitializationAndCategoryTests.cs
      ColumnStandardizationPipelineTests.cs
      ColumnStandardizationPkAndDefectRegressionTests.cs
      ColumnStandardizationTreatmentArmRulesPart1Tests.cs
      ColumnStandardizationTreatmentArmRulesPart2Tests.cs
    TableParserTests.cs                    # Thin shared-parser shell
    TableParserTestHelper.cs
    TableParsing/
      TableParserEfficacyAndRouterTests.cs
      TableParserGeneralRegressionTests.cs
      TableParserPkBasicAndCompoundTests.cs
      TableParserPkHeaderRegressionTests.cs
      TableParserPkRoutingTests.cs
      TableParserPkWaveAndHygieneTests.cs
      TableParserSimpleArmAndAeTests.cs
    DtoLabelAccessFacadeArchitectureTests.cs
    DtoLabelAccessSignatureCompatibilityTests.cs
    LabelControllerRouteCompatibilityTests.cs
    MedRecProPublicSurfaceInventoryTests.cs
    ServiceRegistrationTests.cs

API Endpoints Summary

All API endpoints are accessed under /api in production (IIS virtual application). API controllers inherit the #if DEBUG route in ApiControllerBase, preserving the local /api/[controller] prefix and the production app-relative route where IIS supplies and strips /api.

Authentication (/api/Auth)

Users (/api/Users)

Labels (/api/Label)

The compatibility-stable Label route family contains 51 operations covering navigation views, search, CRUD, import, rendering, and AI features. Internally, those actions are distributed across feature controllers; LabelController and LabelSearchController remain empty shells so the public controller name and Swagger/route contracts stay unchanged.

Navigation & Search Views:

Label Content & Rendering:

Drug Safety:

AI-Powered Endpoints:

CRUD & Import:

Reference:

AI (/api/Ai)

Settings (/api/Settings)

Administrative log endpoints remain Admin-only and return typed, redacted projections. Invalid log filters use validation ProblemDetails; unexpected failures use the global trace-correlated ProblemDetails contract.

Adverse Event Dashboard (/api/AdverseEvent)

Backs the React adverse-event risk dashboard. The whole controller is gated by the FeatureFlags:AeDashboard:Enabled flag (returns 503 when disabled). Reads are anonymous (favorite state is enriched for authenticated users); favorite writes require ApiAccess. Class-picker and MedDRA system-picker responses expose pagination/aggregate totals via the X-Page-Number, X-Page-Size, X-Total-Count, and X-Chartable-Count headers.

MCP Server (/mcp)

The MCP server exposes its own endpoints. See the MedRecProMCP README for full details.

MedRecProStatic and MCP Relationship

MedRecProStatic serves the OAuth/MCP discovery metadata at the domain root because the MCP SDK resolves /.well-known/* relative to the domain, not the MCP endpoint path. When Claude connects to https://www.medrecpro.com/mcp, the SDK looks for discovery at https://www.medrecpro.com/.well-known/oauth-protected-resource and /.well-known/oauth-authorization-server.

These endpoints are registered directly in MedRecProStatic's Program.cs as static JSON responses. Attempts to redirect from the root site to /mcp/.well-known/* failed because 302 redirects cause the MCP SDK to derive the wrong resource URI, and reverse proxying through Cloudflare triggers Bot Fight Mode (403 errors).

MedRecProStatic also has a critical web.config setting (httpErrors existingResponse="PassThrough") placed outside the <location> element so it is inherited by the MCP and API virtual applications. Without this, IIS replaces 401 responses with HTML error pages, breaking the MCP OAuth challenge flow.

Database Schema and SQL Scripts

Database schema definitions and maintenance scripts are maintained in MedRecPro/SQL/. These are the authoritative source for schema updates, view definitions, and index management.

Azure data refresh

For a normal complete local-to-Azure data refresh, start only the unified entry point. It exports and validates the Core, Orange Book, materialized temp, and adverse-event domains before Azure mutation; shows the resolved source/target and inventory; then requires the exact REFRESH server.database.windows.net/MedRecPro confirmation token. It records only non-secret run state under C:\MedRecPro-Migration\Refreshes and attempts index recovery before an incomplete run exits.

.\MedRecPro\SQL\MedRecPro-Azure-Data-Refresh.ps1 `
  -AzureServer "server.database.windows.net" `
  -AzureDatabase "MedRecPro" `
  -AzureUser "migration-user"

A start without an explicit mode first asks for the run mode (validate / export / full refresh; Enter chooses validate-only), and missing Azure connection values are requested interactively with an immediate connection test, so an interactive launch cannot drift into the destructive path by default. Use -ExportOnly to create a validated local snapshot without Azure mutation, -ValidateOnly for source/target preflight, -RefreshExclusionRules only when the normally preserved PharmClassDosageFormExclusion table must be refreshed, and -ResumeRun <run-directory> only for that run's unchanged manifest and data files. -WhatIf previews the stage graph and never acts as destructive authorization. The individual domain workers and nuke/index SQL files remain supported manual/recovery tools; do not combine them with a unified run. When updating database schemas or views, modify the scripts in MedRecPro/SQL/ and run them against the target database. The MedRecPro_Views.sql file is particularly important as the navigation view queries (ingredient search, labeler search, pharmacologic class hierarchy, etc.) are defined there and power many of the API search endpoints. The adverse-event dashboard is backed by the dbo.vw_AeRisk, dbo.vw_AeDrugSummary, and dbo.vw_AeDashboardProductCatalog views (also in MedRecPro_Views.sql), the last two materialized into tmp_ tables by the Stage 5 pipeline so the dashboard reads without runtime statistics.

AI Skills System

The API includes an agentic AI layer that enables natural language interaction with pharmaceutical data. The system follows a request-interpret-execute-synthesize pattern:

1. User submits a natural language query to POST /api/Ai/interpret
2. Claude interprets the query and returns API endpoint specifications
3. The client executes the specified API endpoints
4. Results are sent to POST /api/Ai/synthesize
5. Claude produces a human-readable response with suggested follow-ups

AI skills are defined as markdown prompt files in MedRecPro/Skills/. Key skills include:

• Indication Discovery - Find drugs by indication/use case
• Equianalgesic Conversion - Opioid dose conversion calculations
• Product Extraction - AI-powered extraction of product details from text
• Pharmacologic Class Matching - Map drugs to pharmacologic classifications
• Label Content - Retrieve and synthesize label sections
• Data Rescue - Fallback strategies for missing or incomplete data

Adverse Event Risk Dashboard

The platform turns the free-text adverse-event tables buried in SPL labels into comparable risk statistics and exposes them as an interactive dashboard at /adverse-events.

The data flow spans three projects:

1. MedRecProImportClass / MedRecProConsole — the SPL table-standardization pipeline parses heterogeneous label tables into a uniform analytical schema and, in Stage 5, pre-computes Relative Risk (RR), Dose-Normalized RR (DNRR), and 95% confidence intervals per adverse-event row. Results are materialized into the tmp_FlattenedAdverseEvent* tables. See the MedRecProImportClass README for the full pipeline and the statistical contract.
2. MedRecPro (API) — AdverseEventController (/api/AdverseEvent) serves dashboard-ready, encrypted-ID payloads from the materialized risk views: per-product triage/forest/quadrant, symptom reverse lookup, comparator-aware two-product therapeutic interchange, pharmacologic-class SOC × SOC correlation maps/heatmaps/cell drill-downs, and MedDRA-system-scoped class × class / class × drug correlation views. The feature is gated by FeatureFlags:AeDashboard:Enabled.
3. MedRecProReact — a React + Vite single-page island that renders the product, class, and By System dashboard focuses. Its build output is committed into MedRecProStatic/wwwroot/ae-dashboard and served by MedRecProStatic. See the MedRecProReact README.

Because the observation units for correlation views are intentionally narrow — a single drug within a class for SOC × SOC maps, or shared selected-system terms for By System class-pair maps — sample sizes can be small. The dashboard is deliberately honesty-first: below-floor cells are suppressed rather than fabricated, non-renderable system matrices return warnings, the By System focus is single-system by design, and comparator-mixed payloads are explicitly flagged. The displayed figures are bounded by what each label discloses and what the parser can extract — absence of a signal is not evidence of its absence in practice.

FDA Orange Book Integration

The platform imports and cross-references data from the FDA's Approved Drug Products with Therapeutic Equivalence Evaluations (Orange Book), linking FDA approval records to existing SPL label data.

Orange Book Database Schema

Seven normalized tables store Orange Book data, with three junction tables linking to existing SPL entities:

No foreign key constraints are enforced; relationships are managed by the import module. The main nuke script (MedRecPro-AzureNuke.sql) excludes Orange Book tables, which have their own dedicated truncation script.

Orange Book Import Process

The console application (MedRecProConsole) imports Orange Book data from FDA-published ZIP archives containing tilde-delimited text files. The import pipeline:

Documentation truncated — see the full README on GitHub.