mcp-server-alloy: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is an MCP (Model Context Protocol) server that integrates the Alloy modeling language, allowing LLM-powered agents to generate and execute Alloy code. Alloy is an open source language and analyzer for software modeling used for applications from security mechanism analysis to network design.

Key Dependencies

• @modelcontextprotocol/sdk (^1.7.0): MCP TypeScript SDK for building the server
• alloy-lang (npm package): Bundles the Alloy language binary for Node.js usage
• zod (^3.24.2): Schema validation for tool parameters
• TypeScript (^5.8.2): Development language

Development Commands

• npm run build - Compile TypeScript to JavaScript
• npm run dev - Build and run the server
• npm start - Run the built server
• npm run lint - Check code with ESLint
• npm run lint:fix - Fix auto-fixable ESLint issues
• npm test - Run tests (not yet implemented)

MCP Server Architecture

This project follows the MCP server pattern:

1. Server Setup: Use McpServer from @modelcontextprotocol/sdk/server/mcp.js
2. Transport: Typically uses StdioServerTransport for stdio-based communication
3. Tools: Define tools using server.tool() with zod schemas for parameter validation
4. Resources: Expose data through server.resource() (read-only endpoints)
5. Prompts: Optional reusable templates via server.prompt()

Implementation Pattern

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const server = new McpServer({
  name: "mcp-server-alloy",
  version: "1.0.0"
});

// Define tools for Alloy operations
server.tool("tool-name",
  { param: z.string() },
  async ({ param }) => ({
    content: [{ type: "text", text: "result" }]
  })
);

const transport = new StdioServerTransport();
await server.connect(transport);