CLAUDE.md•3.16 kB
# 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
```typescript
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);
```
## Alloy Integration
The server integrates with the `alloy-lang` npm package which provides a JavaScript wrapper around the Alloy binary:
```typescript
import alloy from "alloy-lang";
const result = alloy.eval("sig Thing {} run { one Thing }");
// Returns structured JSON with instances, values, and solver results
```
The `alloy-lang` package automatically resolves the binary path, so no PATH configuration is needed.
Reference materials:
- [Alloy Tools](https://alloytools.org/)
- [Alloy 6 Overview](https://alloytools.org/alloy6.html)
- [Language Documentation](https://alloytools.org/documentation.html)
- [GitHub Repo](https://github.com/AlloyTools/org.alloytools.alloy)
## Project Structure
- `src/index.ts` - Main server implementation
- `src/alloy-lang.d.ts` - TypeScript type definitions for alloy-lang
- `build/` - Compiled JavaScript output
- `package.json` - ES module configuration (`"type": "module"`)
- Node modules are ES modules (`.js` imports)
## Testing
Use the [MCP Inspector](https://github.com/modelcontextprotocol/inspector) for testing and debugging MCP servers.