@atoms-tech/polarion-mcp 0.1.0

package/README.md

@@ -0,0 +1,108 @@
+# @atoms-tech/polarion-mcp
+
+> Connect any AI IDE to Siemens Polarion ALM in under 2 minutes.
+
+## Prerequisites
+
+1. **Node.js ≥ 18** — [Download](https://nodejs.org/)
+2. **ATOMS API Key** — [Get one free at portal.atoms.tech](https://portal.atoms.tech)
+
+## Installation
+
+### Claude Code
+
+```bash
+claude mcp add polarion-mcp \
+  --env ATOMS_API_KEY=atoms-sk-xxxx \
+  -- npx @atoms-tech/polarion-mcp@0.1.0
+```
+
+### Cursor / VS Code / Windsurf
+
+Add to your MCP settings file (`.cursor/mcp.json`, `.vscode/mcp.json`, etc.):
+
+```json
+{
+  "mcpServers": {
+    "polarion-mcp": {
+      "command": "npx",
+      "args": ["@atoms-tech/polarion-mcp@0.1.0"],
+      "env": {
+        "ATOMS_API_KEY": "atoms-sk-xxxx"
+      }
+    }
+  }
+}
+```
+
+### Other IDEs
+
+Add to your MCP configuration:
+
+```json
+{
+  "mcpServers": {
+    "polarion-mcp": {
+      "command": "npx",
+      "args": ["@atoms-tech/polarion-mcp@0.1.0"],
+      "env": {
+        "ATOMS_API_KEY": "atoms-sk-xxxx"
+      }
+    }
+  }
+}
+```
+
+## How It Works
+
+1. You register at [portal.atoms.tech](https://portal.atoms.tech) and enter your Polarion URL + Personal Access Token (PAT). These are stored securely server-side — never on your machine.
+2. You get an **ATOMS API Key** (`atoms-sk-xxxx`) — the only thing you put in your IDE config.
+3. This package starts a lightweight local MCP bridge and forwards requests to `https://mcp.polarion.atoms.tech/mcp`.
+4. The hosted ATOMS service validates your key, retrieves your Polarion credentials server-side, and executes the Polarion API call on your behalf.
+5. One credit is deducted per successful tool call. Failed calls cost nothing.
+
+## Available Tools
+
+| Tool | Description |
+|------|-------------|
+| `check_connection` | Verify your Polarion connection is working |
+| `list_projects` | List all accessible Polarion projects |
+| `get_project` | Get details about a specific project |
+| `search_workitems` | Search work items with Lucene queries |
+| `get_workitem` | Get a work item by ID |
+| `get_workitem_details` | Get full work item details including custom fields |
+| `get_workitem_history` | Get work item revision history |
+| `list_workitem_types` | List available work item types |
+| `list_custom_fields` | List custom fields for a work item type |
+| `list_spaces` | List document spaces in a project |
+| `list_documents` | List documents in a space |
+| `get_document_info` | Get document metadata |
+| `get_document_outline` | Get document structure |
+| `get_document_section` | Get a specific section |
+| `search_in_document` | Search within a document |
+| `get_workitems_in_module` | Get work items in a module/document |
+
+## Try It
+
+After installation, prompt your AI assistant:
+
+```
+Help me explore my Polarion project with check_connection.
+```
+
+## Plans & Credits
+
+| Plan | Credits/month | Price |
+|------|--------------|-------|
+| Free | 150 | $0 |
+| Starter | 1,500 | $19/mo |
+| Standard | 6,000 | $69/mo |
+| Enterprise | Unlimited | Custom |
+
+Manage credits and billing at [portal.atoms.tech](https://portal.atoms.tech).
+
+## Support
+
+- Docs: [docs.atoms.tech/polarion-mcp](https://docs.atoms.tech/polarion-mcp)
+- Issues: [github.com/atoms-tech/polarion-mcp-server/issues](https://github.com/atoms-tech/polarion-mcp-server/issues)
+- Email: support@atoms.tech

package/bin/polarion-mcp.js

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+/**
+ * @atoms-tech/polarion-mcp
+ *
+ * Entry point for `npx @atoms-tech/polarion-mcp@0.1.0`
+ *
+ * This script:
+ *   1. Validates prerequisites (Node.js + ATOMS_API_KEY env var)
+ *   2. Starts a local stdio MCP bridge
+ *   3. Forwards MCP requests to the hosted ATOMS Polarion MCP endpoint
+ *
+ * No Polarion credentials are stored locally. The hosted ATOMS service resolves
+ * Polarion credentials server-side after validating the ATOMS API key.
+ *
+ * Environment variables:
+ *   ATOMS_API_KEY     (required) Your ATOMS API key from portal.atoms.tech
+ *   ATOMS_MCP_URL     (optional) Override hosted MCP URL for dev/staging
+ */
+
+"use strict";
+
+const { runBridge } = require("../lib/bridge");
+const { checkPrerequisites } = require("../lib/prereqs");
+
+async function main() {
+  // ── 1. Check prerequisites ──────────────────────────────────────────────
+  const precheck = checkPrerequisites();
+  if (!precheck.ok) {
+    process.stderr.write(`\n❌ ATOMS Polarion MCP — prerequisite check failed:\n`);
+    for (const err of precheck.errors) {
+      process.stderr.write(`   • ${err}\n`);
+    }
+    process.stderr.write(`\nSee https://docs.atoms.tech/polarion-mcp/installation for help.\n\n`);
+    process.exit(1);
+  }
+
+  await runBridge({ apiKey: process.env.ATOMS_API_KEY.trim() });
+}
+
+main().catch((err) => {
+  process.stderr.write(`\n❌ Failed to start ATOMS Polarion MCP: ${err.message}\n`);
+  process.stderr.write(
+    "   Check your ATOMS_API_KEY, internet connection, and https://mcp.polarion.atoms.tech/health\n\n"
+  );
+  process.exit(1);
+});

package/lib/bridge.js

@@ -0,0 +1,173 @@
+"use strict";
+
+const { Client } = require("@modelcontextprotocol/sdk/client/index.js");
+const {
+  StreamableHTTPClientTransport,
+} = require("@modelcontextprotocol/sdk/client/streamableHttp.js");
+const { Server } = require("@modelcontextprotocol/sdk/server/index.js");
+const { StdioServerTransport } = require("@modelcontextprotocol/sdk/server/stdio.js");
+const {
+  CallToolRequestSchema,
+  CompleteRequestSchema,
+  GetPromptRequestSchema,
+  ListPromptsRequestSchema,
+  ListResourceTemplatesRequestSchema,
+  ListResourcesRequestSchema,
+  ListToolsRequestSchema,
+  ReadResourceRequestSchema,
+  SubscribeRequestSchema,
+  UnsubscribeRequestSchema,
+} = require("@modelcontextprotocol/sdk/types.js");
+
+const DEFAULT_REMOTE_URL = "https://mcp.polarion.atoms.tech/mcp";
+const DEFAULT_REQUEST_TIMEOUT_MS = 15 * 60 * 1000;
+
+function getRemoteUrl() {
+  return (process.env.ATOMS_MCP_URL || DEFAULT_REMOTE_URL).trim();
+}
+
+function getRequestTimeoutMs() {
+  const raw = process.env.ATOMS_MCP_TIMEOUT_MS || String(DEFAULT_REQUEST_TIMEOUT_MS);
+  const parsed = Number.parseInt(raw, 10);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_REQUEST_TIMEOUT_MS;
+}
+
+function buildRemoteHeaders(apiKey) {
+  return {
+    Authorization: `Bearer ${apiKey}`,
+  };
+}
+
+function buildLocalCapabilities(remoteCapabilities = {}) {
+  const capabilities = {};
+
+  if (remoteCapabilities.tools) {
+    capabilities.tools = {};
+  }
+  if (remoteCapabilities.prompts) {
+    capabilities.prompts = {};
+  }
+  if (remoteCapabilities.resources) {
+    capabilities.resources = {
+      subscribe: Boolean(remoteCapabilities.resources.subscribe),
+    };
+  }
+  if (remoteCapabilities.completions) {
+    capabilities.completions = {};
+  }
+
+  return capabilities;
+}
+
+async function connectRemoteClient({ apiKey, remoteUrl }) {
+  const client = new Client({
+    name: "atoms-polarion-mcp-local-bridge",
+    version: "0.1.0",
+  });
+
+  const transport = new StreamableHTTPClientTransport(new URL(remoteUrl), {
+    requestInit: {
+      headers: buildRemoteHeaders(apiKey),
+    },
+  });
+
+  await client.connect(transport, { timeout: getRequestTimeoutMs() });
+  return { client, transport };
+}
+
+function registerForwardingHandlers(server, remoteClient, capabilities) {
+  const requestOptions = () => ({ timeout: getRequestTimeoutMs() });
+
+  if (capabilities.tools) {
+    server.setRequestHandler(ListToolsRequestSchema, request =>
+      remoteClient.listTools(request.params, requestOptions())
+    );
+    server.setRequestHandler(CallToolRequestSchema, request =>
+      remoteClient.callTool(request.params, undefined, requestOptions())
+    );
+  }
+
+  if (capabilities.prompts) {
+    server.setRequestHandler(ListPromptsRequestSchema, request =>
+      remoteClient.listPrompts(request.params, requestOptions())
+    );
+    server.setRequestHandler(GetPromptRequestSchema, request =>
+      remoteClient.getPrompt(request.params, requestOptions())
+    );
+  }
+
+  if (capabilities.resources) {
+    server.setRequestHandler(ListResourcesRequestSchema, request =>
+      remoteClient.listResources(request.params, requestOptions())
+    );
+    server.setRequestHandler(ListResourceTemplatesRequestSchema, request =>
+      remoteClient.listResourceTemplates(request.params, requestOptions())
+    );
+    server.setRequestHandler(ReadResourceRequestSchema, request =>
+      remoteClient.readResource(request.params, requestOptions())
+    );
+
+    if (capabilities.resources.subscribe) {
+      server.setRequestHandler(SubscribeRequestSchema, request =>
+        remoteClient.subscribeResource(request.params, requestOptions())
+      );
+      server.setRequestHandler(UnsubscribeRequestSchema, request =>
+        remoteClient.unsubscribeResource(request.params, requestOptions())
+      );
+    }
+  }
+
+  if (capabilities.completions) {
+    server.setRequestHandler(CompleteRequestSchema, request =>
+      remoteClient.complete(request.params, requestOptions())
+    );
+  }
+}
+
+async function runBridge({ apiKey, remoteUrl = getRemoteUrl() }) {
+  process.stderr.write(`Connecting to ATOMS Polarion MCP at ${remoteUrl}\n`);
+
+  const { client: remoteClient, transport: remoteTransport } = await connectRemoteClient({
+    apiKey,
+    remoteUrl,
+  });
+
+  const capabilities = buildLocalCapabilities(remoteClient.getServerCapabilities());
+  const server = new Server(
+    {
+      name: "atoms-polarion-mcp",
+      version: "0.1.0",
+    },
+    {
+      capabilities,
+      instructions:
+        "Local bridge for ATOMS Polarion MCP. Tools run through the hosted ATOMS Polarion service.",
+    }
+  );
+
+  registerForwardingHandlers(server, remoteClient, capabilities);
+
+  const stdioTransport = new StdioServerTransport();
+  const close = async () => {
+    await Promise.allSettled([stdioTransport.close(), remoteTransport.close()]);
+  };
+
+  for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"]) {
+    process.once(signal, () => {
+      close().finally(() => process.exit(0));
+    });
+  }
+
+  await server.connect(stdioTransport);
+  process.stderr.write("ATOMS Polarion MCP local bridge is running.\n");
+}
+
+module.exports = {
+  DEFAULT_REMOTE_URL,
+  buildLocalCapabilities,
+  buildRemoteHeaders,
+  getRemoteUrl,
+  getRequestTimeoutMs,
+  registerForwardingHandlers,
+  runBridge,
+};

package/lib/prereqs.js

@@ -0,0 +1,31 @@
+"use strict";
+
+/**
+ * Prerequisite checks run before starting the MCP server.
+ *
+ * @returns {{ ok: boolean, errors: string[] }}
+ */
+function checkPrerequisites() {
+  const errors = [];
+
+  // ATOMS_API_KEY is the only env var required from the user
+  const apiKey = process.env.ATOMS_API_KEY;
+  if (!apiKey) {
+    errors.push(
+      "ATOMS_API_KEY environment variable is not set.\n" +
+      "     Get your API key at https://portal.atoms.tech → Settings → API Keys"
+    );
+  } else if (!apiKey.startsWith("atoms-sk-")) {
+    errors.push(
+      `ATOMS_API_KEY looks invalid (expected format: atoms-sk-xxxx, got: ${apiKey.slice(0, 12)}...)\n` +
+      "     Generate a new key at https://portal.atoms.tech → Settings → API Keys"
+    );
+  }
+
+  return {
+    ok: errors.length === 0,
+    errors,
+  };
+}
+
+module.exports = { checkPrerequisites };

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@atoms-tech/polarion-mcp",
+  "version": "0.1.0",
+  "description": "ATOMS Polarion MCP Server — connect any AI IDE to Siemens Polarion ALM in seconds",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "polarion",
+    "siemens",
+    "alm",
+    "requirements",
+    "atoms"
+  ],
+  "homepage": "https://atoms.tech/polarion-mcp",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/atoms-tech/polarion-mcp-server.git",
+    "directory": "packages/polarion-mcp-npm"
+  },
+  "license": "SEE LICENSE IN LICENSE",
+  "author": "ATOMS.tech <hello@atoms.tech>",
+  "bin": {
+    "polarion-mcp": "./bin/polarion-mcp.js"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "README.md"
+  ],
+  "scripts": {
+    "prepublishOnly": "npm test",
+    "test": "node test/smoke.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^3.25.76"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  }
+}