#1045: ✨ Complete MCP Server Scaffold

[mistryrn]

Summary

Implements a working MCP server for the Arranger introspection API, built on @modelcontextprotocol/sdk v1.x with the Streamable HTTP transport.

Issues

• AIM1-B01: MCP server scaffold #1045

Description of Changes

MCP Server

• Adds @modelcontextprotocol/sdk, zod (v3 for consistency with repo), and pino as dependencies
• Adds configuration via Zod-validated environment variables
• Adds Arranger connection validation at startup
• Adds Pino logger
• Adds an Express server with a configurable MCP endpoint for Streamable HTTP transport
• Adds MCP Resources for the Arranger introspection endpoints:
  • arranger-server-introspection → arranger://introspection/server
  • arranger-sqon-schema → arranger://introspection/sqon
  • arranger-catalog-fields → arranger://introspection/catalog/{catalogId}
• Adds MCP Tools for the Arranger introspection endpoints:
  • list-catalogs
  • get-sqon-schema
  • get-catalog-fields

Special Instructions

Before running these changes, you will need to:

1. Install the new dependencies:

# from project root
npm ci

2. (Optional) Re-build the modules:

# from project root
npm run modules:build

3. Configure environment variables for the mcp-server app:

# from project root
cd apps/mcp-server
cp .env.schema .env

Testing Instructions

Local Arranger

To test the MCP Server against a local instance of Arranger Server:

1. Confirm your apps/mcp-server/.env config aligns with your local Arranger server
2. Ensure ES and Arranger server are running:

# from project root
# start ES (note: you may need to seed ES with `make seed-es` after if this is your first time)
make start-es
# start arranger server (config may vary)
ES_INDEX=file_centric DOCUMENT_TYPE=file CONFIGS_PATH=$(pwd)/docker/server npm run dev:server

3. Start the MCP Server:

# from project root
npm run mcp-server:dev

4. Start the MCP Inspector:

# from project root
npm run mcp-server:inspect

5. You can then open the MCP Inspector URL in your web browser (http://localhost:6274/?MCP_PROXY_AUTH_TOKEN={AUTH_TOKEN}), connect to the MCP Server via Streamable HTTP, and test the Resources and Tools.

Remote Arranger

To test against a remote instance of Arranger Server:

1. Update the ARRANGER_BASE_URL and ARRANGER_CATALOGUES in your MCP Server .env file to point to and reflect the state of your remote Arranger.
2. Follow steps 3-5 of the local testing instructions.

LM Studio

To test with LM Studio instead of MCP Inspector:

• Follow the LM Studio instructions to add an MCP server configuration: https://lmstudio.ai/docs/app/mcp
  • Provide the config JSON in apps/mcp-server/mcp-inspector.json

Readiness Checklist

• Self Review
  • I have performed a self review of code
  • I have run the application locally and manually tested the feature
  • I have checked all updates to correct typos and misspellings
• Formatting
  • Code follows the project style guide
  • Autmated code formatters (ie. Prettier) have been run
• Local Testing
  • Successfully built all packages locally
  • Successfully ran all test suites, all unit and integration tests pass
• Updated Tests
  • Unit and integration tests have been added that describe the bug that was fixed or the features that were added
• Documentation
  • All new environment variables added to .env.schema file and documented in the README
  • All changes to server HTTP endpoints have open-api documentation
  • All new functions exported from their module have TSDoc comment documentation