equilibria-mcp-server 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,142 @@
+# Changelog
+
+All notable changes to the Equilibria MCP Server will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2026-01-02
+
+### Added
+
+#### MCP Server Infrastructure
+- Model Context Protocol server with stdio transport
+- Tool registration framework with 17 MCP tools
+- Session state management for multi-step operations
+- Shared context for incremental document building
+
+#### Economic Model Templates (88 total)
+- **Supply & Demand** (8 templates): basic, surplus, tax, price ceiling, price floor, subsidy, quota, shift
+- **PPF** (4 templates): linear, concave, growth, comparative advantage
+- **Elasticity** (4 templates): demand, total revenue test, comparison, cross elasticity
+- **Production & Cost** (4 templates): short-run production, cost curves, LRAC, profit maximization
+- **Basic Macro** (5 templates): AD-AS basic, AD-AS demand shock, money market, business cycle, Phillips curve
+- **Inequality** (4 templates): Lorenz curve, Laffer curve, progressive tax, income quintiles
+- **Consumer Theory** (11 templates): budget constraints (5 variants), indifference curves (3 types), optimal choice, ICC, PCC
+- **Producer Theory** (5 templates): isoquants, isocost, cost minimization, expansion path, returns to scale
+- **Market Structures** (6 templates): perfect competition (2), monopoly (2), price discrimination (2)
+- **Oligopoly** (5 templates): Cournot, Bertrand, Stackelberg, kinked demand, monopolistic competition
+- **Externalities** (5 templates): negative, positive, Pigouvian tax, Coase theorem, public goods
+- **IS-LM** (5 templates): basic, fiscal policy, monetary policy, policy mix, Mundell-Fleming
+- **Growth** (6 templates): expectations Phillips, supply shock, Solow basic, golden rule, AK model
+- **Intertemporal Macro** (3 templates): Ramsey-Cass-Koopmans, OLG, RBC
+- **New Keynesian** (4 templates): NK IS, NK Phillips, Taylor rule, three-equation
+- **International Trade** (4 templates): Romer endogenous growth, Heckscher-Ohlin, offer curves, terms of trade
+- **Advanced Micro** (4 templates): Edgeworth box, Slutsky equation, principal-agent, mechanism design
+- **Finance & Behavioral** (5 templates): efficient frontier, CAPM, Black-Scholes, prospect theory, hyperbolic discounting
+
+#### MCP Tools
+- **Template Tools**: `generate_economic_model`, `list_available_models`, `get_model_schema`
+- **Model Building Tools**: `create_chart`, `add_curve`, `add_point`, `add_area`, `add_parameter`, `add_annotation`, `add_vertical_line`, `add_horizontal_line`, `export_document`
+- **Validation Tools**: `validate_expression`, `validate_yaml`, `check_dependencies`
+- **Output Tools**: `convert_yaml_to_redux`, `get_economic_formulas`
+
+#### YAML Document Builder
+- Fluent API for constructing Equilibria documents
+- Support for parameters, charts, elements, and annotations
+- Type-safe builder with chainable methods
+
+#### Validation Layer
+- Expression syntax validation using mathjs
+- Zod schema integration with equilibria-engine
+- Circular dependency detection with topological sort
+- Cross-reference validation
+- Levenshtein-based "did you mean" suggestions
+
+#### Economic Knowledge Base
+- 40+ economic formulas (equilibrium, surplus, elasticity, production, utility, cost, macro)
+- Economic constraint validators
+- Default constants and sensible ranges
+
+#### Output Formatters
+- YAML string formatter
+- Redux state object formatter
+- API call sequence formatter (planned)
+
+#### Error Handling (Phase 8)
+- Enhanced error messages with recovery suggestions
+- Error codes and categories for systematic handling
+- Detailed examples in error messages
+- Documentation links in errors
+
+#### Performance Optimizations (Phase 8)
+- Validation caching with LRU eviction
+- Expression validation cache (no TTL)
+- Document validation cache (1 minute TTL)
+- Cache statistics and management utilities
+
+#### Logging & Debugging (Phase 8)
+- Structured logging utility (stderr output)
+- Log levels: debug, info, warn, error
+- Performance measurement helpers
+- Tool invocation logging
+
+#### Documentation
+- Comprehensive tool reference (TOOL_REFERENCE.md)
+- Economic models guide (ECONOMIC_MODELS.md)
+- API documentation (API.md)
+- Usage examples and Claude Desktop configuration
+
+### Testing
+- 291 tests across 7 test suites
+- Template generation tests
+- Tool handler tests
+- Economic validation tests
+- Expression validation tests
+- Builder tests
+- Formatter tests
+
+### Dependencies
+- `@modelcontextprotocol/sdk` - MCP protocol implementation
+- `equilibria-engine` - Graph rendering engine (workspace)
+- `mathjs` - Expression parsing and validation
+- `zod` - Schema validation
+- `js-yaml` - YAML handling
+
+### Technical Details
+- TypeScript with strict mode
+- ES modules
+- Node.js >= 18.0.0
+- Vitest for testing
+
+---
+
+## [0.1.0] - 2025-12-31
+
+### Added
+- Initial project structure
+- MCP server scaffold
+- Basic supply and demand templates
+- Foundation for template library
+
+---
+
+## Future Roadmap
+
+### [1.1.0] - Planned
+- Additional economic model templates
+- Template composition (combining multiple models)
+- Interactive tutorial templates
+- Custom template registration API
+
+### [1.2.0] - Planned
+- Performance profiling and optimization
+- Streaming for large document generation
+- Batch validation API
+- Template versioning
+
+### [2.0.0] - Planned
+- Breaking API improvements based on user feedback
+- Advanced macro models (DSGE extensions)
+- Econometric visualization templates
+- Multi-language support for labels

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kinetonomics
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,240 @@
+# Equilibria MCP Server
+
+A Model Context Protocol (MCP) server that enables AI assistants to generate sophisticated economic visualizations using the Equilibria Engine through natural language interactions.
+
+**Version**: 1.0.0
+**Status**: Production Ready
+
+## Features
+
+- **88 Economic Model Templates** - From high school to postgraduate level
+- **17 MCP Tools** - Complete API for model generation and customization
+- **Multiple Output Formats** - YAML, Redux state, API call sequences
+- **Expression Validation** - Mathematical syntax checking with suggestions
+- **Economic Knowledge Base** - 40+ formulas with validation rules
+
+## Quick Start
+
+### Installation
+
+#### Option 1: Install from NPM (Recommended)
+
+```bash
+npm install -g equilibria-mcp-server
+# or
+pnpm add -g equilibria-mcp-server
+```
+
+#### Option 2: Install from Source
+
+```bash
+# Clone the repository
+git clone https://github.com/DingleDongle93/Equilibria.git
+cd Equilibria/equilibria-monorepo
+
+# Install dependencies
+pnpm install
+
+# Build the MCP server
+pnpm --filter equilibria-mcp-server build
+```
+
+### Claude Desktop Integration
+
+Add to your Claude Desktop configuration:
+
+**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+**Windows**: `%APPDATA%/Claude/claude_desktop_config.json`
+**Linux**: `~/.config/claude/claude_desktop_config.json`
+
+#### If installed via NPM:
+
+```json
+{
+  "mcpServers": {
+    "equilibria": {
+      "command": "equilibria-mcp-server"
+    }
+  }
+}
+```
+
+#### If installed from source:
+
+```json
+{
+  "mcpServers": {
+    "equilibria": {
+      "command": "node",
+      "args": ["/path/to/equilibria-mcp-server/dist/index.js"]
+    }
+  }
+}
+```
+
+### Test the Integration
+
+After configuring, restart Claude Desktop and try:
+
+> "Generate a supply and demand chart with equilibrium at price 50"
+
+## Available Tools
+
+### Template Tools (High-Level)
+| Tool | Description |
+|------|-------------|
+| `generate_economic_model` | Generate complete visualization from template |
+| `list_available_models` | List all available templates by category |
+| `get_model_schema` | Get parameter schema for a template |
+
+### Model Building Tools (Mid-Level)
+| Tool | Description |
+|------|-------------|
+| `create_chart` | Initialize a new chart |
+| `add_curve` | Add curve/line with equation |
+| `add_point` | Add point (explicit or intersection) |
+| `add_area` | Add shaded region |
+| `add_parameter` | Add interactive parameter |
+| `add_annotation` | Add text label |
+| `add_vertical_line` | Add vertical reference line |
+| `add_horizontal_line` | Add horizontal reference line |
+| `export_document` | Export as YAML |
+
+### Validation Tools
+| Tool | Description |
+|------|-------------|
+| `validate_expression` | Check mathematical syntax |
+| `validate_yaml` | Validate document schema |
+| `check_dependencies` | Detect circular dependencies |
+
+### Output Tools
+| Tool | Description |
+|------|-------------|
+| `convert_yaml_to_redux` | Convert to Redux state |
+| `get_economic_formulas` | List economic formulas |
+
+## Economic Models
+
+88 templates across 18 categories:
+
+| Category | Models | Level |
+|----------|--------|-------|
+| Supply & Demand | 8 | High School |
+| PPF | 4 | High School |
+| Elasticity | 4 | High School/Undergrad |
+| Production & Cost | 4 | Undergraduate |
+| Basic Macro | 5 | High School/Undergrad |
+| Inequality | 4 | Undergraduate |
+| Consumer Theory | 11 | Undergraduate |
+| Producer Theory | 5 | Undergraduate |
+| Market Structures | 6 | Undergraduate |
+| Oligopoly | 5 | Undergraduate |
+| Externalities | 5 | Undergraduate |
+| IS-LM | 5 | Undergraduate |
+| Growth | 6 | Undergraduate/Postgrad |
+| Intertemporal Macro | 3 | Postgraduate |
+| New Keynesian | 4 | Postgraduate |
+| International Trade | 4 | Undergraduate/Postgrad |
+| Advanced Micro | 4 | Postgraduate |
+| Finance & Behavioral | 5 | Postgraduate |
+
+See [Economic Models Guide](./docs/ECONOMIC_MODELS.md) for complete documentation.
+
+## Example Usage
+
+### Generate from Template
+
+```
+User: Generate a monopoly model with marginal cost of 25
+
+Claude: [Uses generate_economic_model with model="monopoly_basic" and parameters={marginalCost: 25}]
+```
+
+### Build Custom Model
+
+```
+User: Create a custom chart showing how a tax affects market equilibrium
+
+Claude: [Uses create_chart, add_curve, add_area, add_point, export_document sequentially]
+```
+
+### Validate Expression
+
+```
+User: Is this expression valid? slope * x^2 + intercept
+
+Claude: [Uses validate_expression to check syntax]
+```
+
+## Development
+
+```bash
+# Development mode with hot reload
+pnpm dev
+
+# Run tests
+pnpm test
+
+# Type check
+pnpm type-check
+
+# Build
+pnpm build
+```
+
+### Test Coverage
+
+- 291 tests across 7 test files
+- Template generation tests
+- Tool handler tests
+- Economic validation tests
+- Expression validation tests
+
+## Documentation
+
+- [Tool Reference](./docs/TOOL_REFERENCE.md) - Complete tool documentation
+- [Economic Models Guide](./docs/ECONOMIC_MODELS.md) - All 88 model templates
+- [API Documentation](./docs/API.md) - Integration and programmatic usage
+- [Implementation Plan](./docs/IMPLEMENTATION_PLAN.md) - Development roadmap
+- [Examples](./examples/) - Usage examples and Claude Desktop config
+
+## Architecture
+
+```
+equilibria-mcp-server/
+├── src/
+│   ├── index.ts           # Entry point
+│   ├── server.ts          # MCP server setup
+│   ├── builders/          # YAML document builder
+│   ├── economics/         # Formulas, validators, constants
+│   ├── formatters/        # Output formatters
+│   ├── templates/         # 88 economic model templates
+│   ├── tools/             # MCP tool implementations
+│   ├── types/             # TypeScript types
+│   └── validation/        # Expression & document validation
+├── docs/                  # Documentation
+├── examples/              # Usage examples
+└── __tests__/             # Test suites
+```
+
+## Technical Stack
+
+- **Language**: TypeScript
+- **MCP SDK**: @modelcontextprotocol/sdk
+- **Engine**: equilibria-engine (monorepo)
+- **Validation**: Zod schemas
+- **Math Parsing**: mathjs
+- **Testing**: Vitest
+
+## Requirements
+
+- Node.js >= 18.0.0
+- pnpm (recommended) or npm
+
+## License
+
+MIT
+
+---
+
+**Questions?** See the [documentation](./docs/) or [examples](./examples/).

package/dist/builders/YAMLBuilder.d.ts

@@ -0,0 +1,77 @@
+/**
+ * YAML Document Builder
+ *
+ * Fluent API for constructing Equilibria YAML documents programmatically.
+ */
+import type { ParameterConfig, ChartConfig, ElementConfig, AnnotationConfig } from '../types/index.js';
+/**
+ * Builder class for constructing Equilibria documents
+ */
+export declare class YAMLBuilder {
+    private state;
+    constructor();
+    /**
+     * Set document title
+     */
+    setTitle(title: string): this;
+    /**
+     * Set document description
+     */
+    setDescription(description: string): this;
+    /**
+     * Set spec version
+     */
+    setSpecVersion(version: string): this;
+    /**
+     * Add a global parameter
+     */
+    addParameter(name: string, config: ParameterConfig, chartId?: string): this;
+    /**
+     * Add multiple parameters at once
+     */
+    addParameters(params: Record<string, ParameterConfig>, chartId?: string): this;
+    /**
+     * Add a chart
+     */
+    addChart(config: ChartConfig): this;
+    /**
+     * Get a chart by ID
+     */
+    getChart(chartId: string): ChartConfig | undefined;
+    /**
+     * Add an element to a chart
+     */
+    addElement(chartId: string, element: ElementConfig): this;
+    /**
+     * Add an annotation to a chart
+     */
+    addAnnotation(chartId: string, annotation: AnnotationConfig): this;
+    /**
+     * Build the final document object
+     */
+    build(): Record<string, unknown>;
+    /**
+     * Format parameters for output
+     */
+    private formatParameters;
+    /**
+     * Format a chart for output
+     */
+    private formatChart;
+    /**
+     * Reset the builder to initial state
+     */
+    reset(): this;
+}
+/**
+ * Convenience function to create a supply and demand document
+ */
+export declare function createSupplyDemandDocument(options: {
+    title?: string;
+    demandIntercept?: number;
+    demandSlope?: number;
+    supplyIntercept?: number;
+    supplySlope?: number;
+    showSurplus?: boolean;
+}): Record<string, unknown>;
+//# sourceMappingURL=YAMLBuilder.d.ts.map

package/dist/builders/YAMLBuilder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"YAMLBuilder.d.ts","sourceRoot":"","sources":["../../src/builders/YAMLBuilder.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAEV,eAAe,EACf,WAAW,EACX,aAAa,EACb,gBAAgB,EACjB,MAAM,mBAAmB,CAAC;AAE3B;;GAEG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,KAAK,CAAe;;IAY5B;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAK7B;;OAEG;IACH,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI;IAKzC;;OAEG;IACH,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAKrC;;OAEG;IACH,YAAY,CACV,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,eAAe,EACvB,OAAO,CAAC,EAAE,MAAM,GACf,IAAI;IAeP;;OAEG;IACH,aAAa,CACX,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,EACvC,OAAO,CAAC,EAAE,MAAM,GACf,IAAI;IAOP;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI;IAKnC;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS;IAIlD;;OAEG;IACH,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,GAAG,IAAI;IAQzD;;OAEG;IACH,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,gBAAgB,GAAG,IAAI;IAWlE;;OAEG;IACH,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAwBhC;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAsBxB;;OAEG;IACH,OAAO,CAAC,WAAW;IAmBnB;;OAEG;IACH,KAAK,IAAI,IAAI;CAUd;AAED;;GAEG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,EAAE;IAClD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CA0E1B"}