{"_id":"@calcslive/mcp-server","_rev":"2-bd2d6023dfcfa80d94262644b48f5c7e","name":"@calcslive/mcp-server","dist-tags":{"latest":"1.0.1"},"versions":{"1.0.0":{"name":"@calcslive/mcp-server","version":"1.0.0","keywords":["mcp","model-context-protocol","calcslive","engineering","calculations","unit-aware","unit-aware-calculations","unit-conversion","ai-agent","claude","anthropic","physics","mathematics","scientific-computing"],"author":{"name":"CalcsLive"},"license":"MIT","_id":"@calcslive/mcp-server@1.0.0","maintainers":[{"name":"e3d","email":"dongsheng.wen@gmail.com"}],"homepage":"https://github.com/CalcsLive/calcslive-mcp-server#readme","bugs":{"url":"https://github.com/CalcsLive/calcslive-mcp-server/issues"},"bin":{"calcslive-mcp":"dist/index.js"},"dist":{"shasum":"25e53e020038d37814a96c99edf7a18a0ac2c270","tarball":"https://registry.npmjs.org/@calcslive/mcp-server/-/mcp-server-1.0.0.tgz","fileCount":10,"integrity":"sha512-dvnxMblBnCszMYRVpoFKnofcoCZ3tW7r0kZ54CHvdN7cTMB7ypX0aLKyYEYd/q2In5YAk8x+K6SqbglAs+yrkA==","signatures":[{"sig":"MEYCIQDMW2b0T/0fpDNhbdVy8YJEXjrFfiiwQwYviBhD520/EQIhAIAigscNcWlLm64IBL5cntSvMsK2GVZ1JACUFQCW7WbO","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":56173},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","engines":{"node":">=18.0.0"},"gitHead":"8ca31cfc8f96e3e24651600add469196b3b752e2","scripts":{"dev":"tsc --watch","build":"tsc","start":"node dist/index.js","prepublishOnly":"npm run build"},"_npmUser":{"name":"e3d","email":"dongsheng.wen@gmail.com"},"repository":{"url":"git+https://github.com/CalcsLive/calcslive-mcp-server.git","type":"git"},"_npmVersion":"9.4.1","description":"CalcsLive MCP server for AI agents - enables accurate unit-aware engineering calculations via Model Context Protocol","directories":{},"_nodeVersion":"24.6.0","dependencies":{"dotenv":"^17.2.3","@modelcontextprotocol/sdk":"^0.5.0"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.3.0","@types/node":"^20.0.0"},"_npmOperationalInternal":{"tmp":"tmp/mcp-server_1.0.0_1765932394365_0.9991013044337307","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@calcslive/mcp-server","version":"1.0.1","description":"CalcsLive MCP server for AI agents - enables accurate unit-aware engineering calculations via Model Context Protocol","type":"module","main":"dist/index.js","types":"dist/index.d.ts","bin":{"calcslive-mcp":"dist/index.js"},"scripts":{"build":"tsc","dev":"tsc --watch","start":"node dist/index.js","prepublishOnly":"npm run build"},"keywords":["mcp","model-context-protocol","calcslive","engineering","calculations","unit-aware","unit-aware-calculations","unit-conversion","ai-agent","claude","anthropic","physics","mathematics","scientific-computing"],"author":{"name":"CalcsLive"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/CalcsLive/calcslive-mcp-server.git"},"bugs":{"url":"https://github.com/CalcsLive/calcslive-mcp-server/issues"},"homepage":"https://github.com/CalcsLive/calcslive-mcp-server#readme","dependencies":{"@modelcontextprotocol/sdk":"^0.5.0","dotenv":"^17.2.3"},"devDependencies":{"@types/node":"^20.0.0","typescript":"^5.3.0"},"engines":{"node":">=18.0.0"},"gitHead":"5b8db9f813a3e3b3317e69641307536da6d72289","_id":"@calcslive/mcp-server@1.0.1","_nodeVersion":"24.6.0","_npmVersion":"9.4.1","dist":{"integrity":"sha512-CYPqiPwEx9n9xM8OhGq++89I8cN7tUSeoTnerXvE+DOCtzGZwQdYhHgsfpz/NW43ZPF9m3UwSMKaN5g2Fv8yJw==","shasum":"1e924ff347edd290fcc40b97ff10c8de835948da","tarball":"https://registry.npmjs.org/@calcslive/mcp-server/-/mcp-server-1.0.1.tgz","fileCount":10,"unpackedSize":56165,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIERF612aqROrtoR1nMp+lNPr/cs1iOIdlN2fN1i7h/YcAiEA71ecYf6647W9sduzgWtuO6VxkrUJIkaetw45ggj03v4="}]},"_npmUser":{"name":"e3d","email":"dongsheng.wen@gmail.com"},"directories":{},"maintainers":[{"name":"e3d","email":"dongsheng.wen@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mcp-server_1.0.1_1765951768995_0.21069548088827084"},"_hasShrinkwrap":false}},"time":{"created":"2025-12-17T00:46:34.242Z","modified":"2025-12-17T06:09:29.349Z","1.0.0":"2025-12-17T00:46:34.499Z","1.0.1":"2025-12-17T06:09:29.145Z"},"bugs":{"url":"https://github.com/CalcsLive/calcslive-mcp-server/issues"},"author":{"name":"CalcsLive"},"license":"MIT","homepage":"https://github.com/CalcsLive/calcslive-mcp-server#readme","keywords":["mcp","model-context-protocol","calcslive","engineering","calculations","unit-aware","unit-aware-calculations","unit-conversion","ai-agent","claude","anthropic","physics","mathematics","scientific-computing"],"repository":{"type":"git","url":"git+https://github.com/CalcsLive/calcslive-mcp-server.git"},"description":"CalcsLive MCP server for AI agents - enables accurate unit-aware engineering calculations via Model Context Protocol","maintainers":[{"name":"e3d","email":"dongsheng.wen@gmail.com"}],"readme":"# CalcsLive MCP Server\r\n\r\n**Enable AI agents to perform unit-aware engineering calculations via Model Context Protocol (MCP)**\r\n\r\nTransform AI assistants like Claude into powerful engineering calculation tools with automatic unit conversion, dependency resolution, and professional-grade accuracy.\r\n\r\n## 🎯 What is This?\r\n\r\nThe CalcsLive MCP Server connects AI agents to [CalcsLive](https://www.calcs.live)'s calculation engine via the [Model Context Protocol (MCP)](https://modelcontextprotocol.io). This enables AI to:\r\n\r\n- ✅ Perform complex engineering calculations with proper unit handling\r\n- ✅ Automatically convert between unit systems (metric ↔ imperial)\r\n- ✅ Resolve multi-step calculation dependencies\r\n- ✅ Access 75+ unit categories with 500+ units\r\n- ✅ Validate calculations with engineering accuracy\r\n\r\n### Example\r\n\r\n**User**: \"Calculate hydro power for a flow rate of 150 m³/s with a head of 25 meters\"\r\n\r\n**AI (via CalcsLive MCP)**:\r\n```json\r\n{\r\n  \"power\": {\r\n    \"value\": 36787.5,\r\n    \"unit\": \"kW\"\r\n  }\r\n}\r\n```\r\n\r\nAI automatically handles the unit-aware calculation: P = ρ × g × H × Q × η\r\n\r\n---\r\n\r\n## 📋 Prerequisites\r\n\r\n1. **Node.js 18+** installed on your system\r\n2. **CalcsLive Account** - Sign up at [calcs.live](https://www.calcs.live)\r\n3. **MCP API Key** - Create from your [Account > API Keys](https://www.calcs.live/account/api-keys)\r\n   - Select \"MCP Integration (AI Agents)\" as service type\r\n   - **Free users**: Get 30-day trial (starts on first API call)\r\n   - **Premium users**: Full unlimited access\r\n\r\n---\r\n\r\n## 🚀 Quick Start\r\n\r\n### 1. Install Dependencies\r\n\r\n```bash\r\ncd /path/to/calcslive-mcp-server\r\nnpm install\r\n```\r\n\r\n### 2. Build the Server\r\n\r\n```bash\r\nnpm run build\r\n```\r\n\r\n### 3. Configure Claude Desktop\r\n\r\nEdit your Claude Desktop configuration file:\r\n\r\n**Location**:\r\n- **Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\r\n- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\r\n- **Linux**: `~/.config/Claude/claude_desktop_config.json`\r\n\r\n**Add CalcsLive MCP server**:\r\n\r\n```json\r\n{\r\n  \"mcpServers\": {\r\n    \"calcslive\": {\r\n      \"command\": \"node\",\r\n      \"args\": [\r\n        \"/absolute/path/to/calcslive-mcp-server/dist/index.js\"\r\n      ],\r\n      \"env\": {\r\n        \"CALCSLIVE_API_KEY\": \"your-mcp-api-key-here\",\r\n        \"CALCSLIVE_API_URL\": \"https://www.calcs.live\"\r\n      }\r\n    }\r\n  }\r\n}\r\n```\r\n\r\n**Important**:\r\n- Replace `/absolute/path/to/calcslive-mcp-server` with your actual installation path\r\n- Replace `your-mcp-api-key-here` with your actual MCP API key from CalcsLive\r\n\r\n### 4. Restart Claude Desktop\r\n\r\nQuit and restart Claude Desktop to load the MCP server.\r\n\r\n### 5. Verify Installation\r\n\r\nIn Claude Desktop, you should see the CalcsLive tools available. Try asking:\r\n\r\n> \"What CalcsLive tools do you have available?\"\r\n\r\nClaude should list `calcslive_run_script`, `calcslive_calculate`, and `calcslive_validate`.\r\n\r\n---\r\n\r\n## 🔧 Claude Code (VS Code Extension) Setup\r\n\r\nIf you're using Claude Code in VS Code, use the Claude CLI for easier configuration:\r\n\r\n### 1. Install and Build\r\n\r\n```bash\r\ncd /path/to/calcslive-mcp-server\r\nnpm install\r\nnpm run build\r\n```\r\n\r\n### 2. Add MCP Server via Claude CLI\r\n\r\nUse the `claude mcp add` command with stdio transport:\r\n\r\n**Linux/macOS**:\r\n```bash\r\nclaude mcp add --scope user --transport stdio calcslive node \\\r\n  --env CALCSLIVE_API_KEY=your-mcp-api-key-here \\\r\n  --env CALCSLIVE_API_URL=https://www.calcs.live \\\r\n  -- /absolute/path/to/calcslive-mcp-server/dist/index.js\r\n```\r\n\r\n**Windows PowerShell**:\r\n```powershell\r\nclaude mcp add --scope user --transport stdio calcslive node `\r\n  --env CALCSLIVE_API_KEY=your-mcp-api-key-here `\r\n  --env CALCSLIVE_API_URL=https://www.calcs.live `\r\n  -- C:\\absolute\\path\\to\\calcslive-mcp-server\\dist\\index.js\r\n```\r\n\r\n**Important Notes**:\r\n- **`--scope user`**: Makes MCP available in **all VS Code windows** (recommended for global access)\r\n  - Without `--scope user`, MCP only works in the current project directory\r\n  - Alternative scopes: `local` (project-specific), `project` (shared in team)\r\n- **Command structure**: `calcslive node` where `node` is the command and path comes after `--`\r\n- Replace `/absolute/path/to/calcslive-mcp-server` (or `C:\\absolute\\path\\to\\...` on Windows) with your actual installation path\r\n- Replace `your-mcp-api-key-here` with your actual API key from [CalcsLive API Keys](https://www.calcs.live/account/api-keys)\r\n- For local development, use `CALCSLIVE_API_URL=http://localhost:3000`\r\n\r\n### 3. Verify in VS Code\r\n\r\nRestart your VS Code window or reload Claude Code extension. The CalcsLive MCP tools should now be available to Claude Code AI.\r\n\r\n**Test it**:\r\n> \"Calculate the torque for a 2 HP motor running at 100 rpm\"\r\n\r\nClaude Code should use the `calcslive_run_script` tool to perform the calculation.\r\n\r\n### Alternative: Manual Configuration\r\n\r\nIf Claude CLI is not available, you can manually edit the Claude Code MCP configuration file, but the CLI method is **strongly recommended** for reliability.\r\n\r\n---\r\n\r\n## 🛠️ Available Tools\r\n\r\n### `calcslive_run_script` ⭐ NEW\r\n\r\nRun stateless unit-aware calculations from Physical Quantity (PQ) script definitions. No article creation needed - fully stateless and on-the-fly.\r\n\r\n**Example Usage**:\r\n```\r\nUser: \"Calculate the area of a circle with radius 5 cm in mm²\"\r\n\r\nAI uses: calcslive_run_script\r\n- pqs: [\r\n    {\r\n      sym: \"r\",\r\n      description: \"radius\",\r\n      value: 5,\r\n      unit: \"cm\"\r\n    },\r\n    {\r\n      sym: \"A\",\r\n      description: \"circle area\",\r\n      expression: \"pi * r^2\",\r\n      unit: \"cm²\"\r\n    }\r\n  ]\r\n- outputs: {\r\n    A: { unit: \"mm²\" }\r\n  }\r\n```\r\n\r\n**Response**:\r\n```\r\nCalculation completed with 1 output\r\n\r\nResults:\r\n• circle area (A): 7853.982 mm² = pi * r^2\r\n\r\nDetailed calculation:\r\n{\r\n  \"inputs\": {\r\n    \"r\": { \"value\": 5, \"unit\": \"cm\", \"baseValue\": 0.05, \"baseUnit\": \"m\" }\r\n  },\r\n  \"outputs\": {\r\n    \"A\": { \"value\": 7853.982, \"unit\": \"mm²\", \"baseValue\": 0.007854, \"baseUnit\": \"m²\" }\r\n  }\r\n}\r\n```\r\n\r\n**Key Features**:\r\n- ✅ No article creation required (stateless)\r\n- ✅ Define calculations on-the-fly with PQ JSON\r\n- ✅ Supports Greek letters (α, β, η, ρ, etc.)\r\n- ✅ Automatic dependency resolution\r\n- ✅ Unit conversion for inputs and outputs\r\n- ✅ Mathematical expressions with MathJS\r\n\r\n### `calcslive_calculate`\r\n\r\nPerform unit-aware calculations using existing CalcsLive articles.\r\n\r\n**Example Usage**:\r\n```\r\nUser: \"Calculate the kinetic energy of a 1500 kg car traveling at 25 m/s\"\r\n\r\nAI uses: calcslive_calculate\r\n- articleId: \"kinetic-energy\"\r\n- inputs: {\r\n    mass: { value: 1500, unit: \"kg\" },\r\n    velocity: { value: 25, unit: \"m/s\" }\r\n  }\r\n- outputs: {\r\n    energy: { unit: \"kJ\" }\r\n  }\r\n```\r\n\r\n**Response**:\r\n```json\r\n{\r\n  \"energy\": {\r\n    \"value\": 468.75,\r\n    \"unit\": \"kJ\",\r\n    \"expression\": \"0.5 * mass * velocity^2\"\r\n  }\r\n}\r\n```\r\n\r\n### `calcslive_validate`\r\n\r\nDiscover available inputs/outputs for a calculation article.\r\n\r\n**Example Usage**:\r\n```\r\nUser: \"What parameters does the hydro power calculation accept?\"\r\n\r\nAI uses: calcslive_validate\r\n- articleId: \"hydro-power\"\r\n```\r\n\r\n**Response**:\r\n```json\r\n{\r\n  \"articleTitle\": \"Hydro Power Calculation\",\r\n  \"inputPQs\": [\r\n    {\r\n      \"symbol\": \"Q\",\r\n      \"description\": \"Flow rate\",\r\n      \"unit\": \"m³/s\",\r\n      \"categoryId\": \"volumetric_flow_rate\"\r\n    },\r\n    {\r\n      \"symbol\": \"H\",\r\n      \"description\": \"Head\",\r\n      \"unit\": \"m\",\r\n      \"categoryId\": \"length\"\r\n    }\r\n  ],\r\n  \"outputPQs\": [\r\n    {\r\n      \"symbol\": \"P\",\r\n      \"description\": \"Power output\",\r\n      \"unit\": \"kW\",\r\n      \"expression\": \"rho * g * H * Q * eta\"\r\n    }\r\n  ]\r\n}\r\n```\r\n\r\n---\r\n\r\n## 💡 Usage Examples\r\n\r\n### Example 1: Unit Conversion\r\n\r\n**User**: \"Convert 65 mph to km/h\"\r\n\r\n**AI**: Uses CalcsLive to create a simple calculation:\r\n```\r\nInput: velocity = 65 mph\r\nOutput: velocity in km/h = 104.6 km/h\r\n```\r\n\r\n### Example 2: Multi-Step Engineering Calculation\r\n\r\n**User**: \"Calculate pump power needed for 100 gallons per minute at 50 psi with 85% efficiency\"\r\n\r\n**AI**:\r\n1. Validates pump calculation article\r\n2. Converts units (gpm → m³/s, psi → Pa)\r\n3. Performs calculation with dependencies\r\n4. Returns power in kW\r\n\r\n### Example 3: Complex Physics Problem\r\n\r\n**User**: \"A projectile is launched at 45° with initial velocity 30 m/s. What's the maximum height?\"\r\n\r\n**AI**:\r\n1. Uses projectile motion calculation article\r\n2. Inputs: angle = 45°, velocity = 30 m/s\r\n3. Calculates: max_height = (v² × sin²θ) / (2g) = 22.96 m\r\n\r\n---\r\n\r\n## 🔧 Development\r\n\r\n### Build & Watch\r\n\r\n```bash\r\nnpm run dev\r\n```\r\n\r\nThis runs TypeScript in watch mode for development.\r\n\r\n### Testing Locally\r\n\r\nRun the server directly to test:\r\n\r\n```bash\r\nexport CALCSLIVE_API_KEY=your_key_here\r\nnpm start\r\n```\r\n\r\nYou should see:\r\n```\r\nCalcsLive MCP server running on stdio\r\nAPI Base: https://www.calcs.live\r\nReady to perform unit-aware calculations for AI agents!\r\n```\r\n\r\n---\r\n\r\n## 📊 API Rate Limits\r\n\r\n| User Tier | Rate Limit | Trial Period |\r\n|-----------|------------|--------------|\r\n| **Free** | 60 calls/min | 30 days |\r\n| **Premium** | 60 calls/min | N/A (unlimited) |\r\n| **Enterprise** | Unlimited | N/A |\r\n\r\n**Note**: Trial starts automatically on first API call. Upgrade to Premium before trial expires for continued access.\r\n\r\n---\r\n\r\n## 🐛 Troubleshooting\r\n\r\n### \"API key not found or inactive\"\r\n\r\n**Solution**: Check your API key in [Account > API Keys](https://www.calcs.live/account/api-keys)\r\n- Ensure service type is \"MCP Integration (AI Agents)\"\r\n- Verify key is active (not expired)\r\n- Copy key exactly (no extra spaces)\r\n\r\n### \"Article not found\"\r\n\r\n**Solution**:\r\n- Ensure article is set to **Public** access level\r\n- Use the article's **Short ID**, not UUID\r\n- Verify you own the article (can't access others' articles via API)\r\n\r\n### \"Trial has expired\"\r\n\r\n**Solution**: [Upgrade to Premium](https://www.calcs.live/pricing) to restore MCP access\r\n\r\n### Claude Desktop Not Finding Tools\r\n\r\n**Solution**:\r\n1. Check config file syntax (valid JSON)\r\n2. Verify path to `dist/index.js` is correct\r\n3. Ensure `npm run build` completed successfully\r\n4. Restart Claude Desktop completely\r\n5. Check Claude Desktop logs for errors\r\n\r\n### \"Unknown unit\" Error\r\n\r\n**Solution**:\r\n- CalcsLive supports both superscript (m³) and caret (m^3) notation\r\n- Use caret notation if typing: `m^3` instead of `m³`\r\n- Check [Units Reference](https://www.calcs.live/help/units-reference) for valid units\r\n\r\n---\r\n\r\n## 🌟 Advanced Usage\r\n\r\n### Custom API Base URL (Development)\r\n\r\nFor local development or custom deployments:\r\n\r\n```json\r\n{\r\n  \"mcpServers\": {\r\n    \"calcslive\": {\r\n      \"env\": {\r\n        \"CALCSLIVE_API_URL\": \"http://localhost:3000\",\r\n        \"CALCSLIVE_API_KEY\": \"your-dev-key\"\r\n      }\r\n    }\r\n  }\r\n}\r\n```\r\n\r\n### Multiple API Keys\r\n\r\nYou can configure separate MCP servers for different projects:\r\n\r\n```json\r\n{\r\n  \"mcpServers\": {\r\n    \"calcslive-project-a\": {\r\n      \"command\": \"node\",\r\n      \"args\": [\"...\"],\r\n      \"env\": {\r\n        \"CALCSLIVE_API_KEY\": \"project-a-key\"\r\n      }\r\n    },\r\n    \"calcslive-project-b\": {\r\n      \"command\": \"node\",\r\n      \"args\": [\"...\"],\r\n      \"env\": {\r\n        \"CALCSLIVE_API_KEY\": \"project-b-key\"\r\n      }\r\n    }\r\n  }\r\n}\r\n```\r\n\r\n---\r\n\r\n## 📚 Resources\r\n\r\n- **CalcsLive Platform**: [calcs.live](https://www.calcs.live)\r\n- **MCP Documentation**: [modelcontextprotocol.io](https://modelcontextprotocol.io)\r\n- **Units Reference**: [calcs.live/help/units-reference](https://www.calcs.live/help/units-reference)\r\n- **API Integration Guide**: [calcs.live/help/api-integration](https://www.calcs.live/help/api-integration)\r\n- **Create Calculations**: [calcs.live/editor/new](https://www.calcs.live/editor/new)\r\n\r\n---\r\n\r\n## 🤝 Support\r\n\r\n- **Documentation**: [calcs.live/help](https://www.calcs.live/help)\r\n- **Community**: [GitHub Discussions](https://github.com/calcslive/discussions)\r\n- **Premium Support**: Available for Premium/Enterprise subscribers\r\n\r\n---\r\n\r\n## 📝 License\r\n\r\nMIT License - See LICENSE file for details\r\n\r\n---\r\n\r\n## 🚀 What's Next?\r\n\r\n1. **Create Custom Calculations**: Build your own calculation articles at [calcs.live/editor/new](https://www.calcs.live/editor/new)\r\n2. **Explore Unit Categories**: Browse 75+ categories at [Units Reference](https://www.calcs.live/help/units-reference)\r\n3. **Upgrade for More**: [Premium plans](https://www.calcs.live/pricing) unlock unlimited calculations\r\n4. **Share & Collaborate**: Make calculations public for others to use via MCP\r\n\r\n---\r\n\r\n**Built with ❤️ for AI-powered engineering**\r\n","readmeFilename":"README.md"}