@softacus-software/elwis-docs-mcp 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this project adheres
+to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.1] - 2026-07-06
+
+### Changed
+- Simpler step-by-step README with client configuration examples.
+- Packaged file list trimmed to runtime files.
+
+## [0.1.0] - 2026-07-02
+
+### Added
+- Initial standalone release of the read-only ELWIS API documentation MCP server.
+- Five STDIO tools: `search_elwis_api`, `list_elwis_api_groups`, `get_elwis_endpoint`,
+  `get_elwis_schema`, `get_elwis_examples`, registered with read-only tool annotations,
+  titles, and described parameters.
+- Byte-bounded schema resolution: `get_elwis_schema` lowers the inlining depth
+  automatically when a response would exceed the budget and reports `depthUsed`,
+  `truncatedRefs` (expandable), and `missingRefs` (documentation gaps) separately.
+- Search results carry `total`, `returned`, and `hasMore` pagination metadata;
+  plural query tokens match singular keywords.
+- Endpoint details report the request content type, so non-JSON (multipart) bodies
+  are visible.
+- Deterministic generation of MCP data from the ELWIS OpenAPI specification
+  (`export-spec` + `generate`, combined as `refresh`) with a normalization-consistent
+  `check-drift` gate; both honor `ELWIS_SWAGGER_URL` and support HTTPS.
+- Agent skill (`skill/elwis-api`) shipped inside the npm package.
+- Test suite covering parsers, search, data store, the MCP protocol layer, and
+  byte-size sweeps over every schema, endpoint, and examples response.

package/LICENSE

@@ -0,0 +1,6 @@
+Copyright (c) 2026 Softacus. All rights reserved.
+
+This software and its source code are proprietary and confidential to Softacus.
+No part of this package may be copied, modified, distributed, published, or used
+except with the express prior written permission of Softacus, or under the terms
+of a separate written agreement. Unauthorized use is prohibited.

package/README.md

@@ -0,0 +1,112 @@
+# @softacus-software/elwis-docs-mcp
+
+A read-only [Model Context Protocol](https://modelcontextprotocol.io) server that teaches your chat client the ELWIS REST API. Ask about endpoints, parameters, schemas, and examples in plain words. Everything is generated from the OpenAPI specification, so the answers cannot disagree with the documented API.
+
+It serves knowledge about the API only. It never connects to a live ELWIS and cannot read or write any data.
+
+```
++-------------------+        +---------------------+        +-------------+
+|  Your chat client |  <-->  |  elwis-docs-mcp     |  <---  |  OpenAPI    |
+|  (Claude Desktop, |        |  (this server,      |        |  spec       |
+|  Codex, Gemini)   |        |  runs on your       |        |  (bundled)  |
+|                   |        |  computer)          |        |             |
++-------------------+        +---------------------+        +-------------+
+```
+
+## Set up in three minutes
+
+### Step 1. Install Node.js (one time)
+
+Go to [nodejs.org](https://nodejs.org), download the LTS installer, run it, accept the defaults. Check it in a terminal:
+
+```bash
+node --version
+```
+
+### Step 2. Sign in to npm (one time)
+
+The package is private to the Softacus team. Ask your administrator to invite you to the softacus organization on npmjs.com (you need a free npm account), then run:
+
+```bash
+npm login
+```
+
+A browser window opens; sign in with your npm account and return to the terminal.
+
+### Step 3. Add the server to your client
+
+Claude Desktop (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS, `%APPDATA%\Claude\claude_desktop_config.json` on Windows) and Claude Code (`.mcp.json` in the project root, same shape):
+
+```json
+{
+  "mcpServers": {
+    "elwis-docs": {
+      "command": "npx",
+      "args": ["-y", "@softacus-software/elwis-docs-mcp"]
+    }
+  }
+}
+```
+
+Codex (`~/.codex/config.toml`):
+
+```toml
+[mcp_servers.elwis-docs]
+command = "npx"
+args = ["-y", "@softacus-software/elwis-docs-mcp"]
+```
+
+Gemini CLI (`~/.gemini/settings.json`): same JSON shape as Claude Desktop.
+
+No ELWIS address, no ELWIS login. There is nothing else to configure because it never talks to a live system.
+
+### Step 4. Check it works
+
+Fully quit your client (on a Mac press Cmd+Q), open it again, and ask:
+
+```
+Which ELWIS endpoint creates an attribute?
+```
+
+You should get the exact endpoint with its method, parameters, and a worked example.
+
+## What to ask
+
+```
+How do I create an application through the ELWIS API?
+What fields does the artifact type update request take?
+Show me an example request for creating a link type.
+What does the data type schema look like?
+```
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `search_elwis_api` | Find endpoints by intent, like "create an attribute" |
+| `list_elwis_api_groups` | Browse the API area by area |
+| `get_elwis_endpoint` | Full detail of one endpoint: method, path, parameters, schemas |
+| `get_elwis_schema` | One request or response schema, depth-bounded |
+| `get_elwis_examples` | Verified worked examples for an endpoint |
+
+Every response is size-bounded (typically 1 to 6 KB), so it stays friendly to the client's context. Unknown names return clean errors with near-miss suggestions instead of guesses.
+
+## Keeping it up to date
+
+The data is generated deterministically from the ELWIS OpenAPI spec:
+
+```bash
+npm run export-spec   # fetch the current spec from a running ELWIS
+npm run generate      # rebuild data/ from it
+npm run check-drift   # fails when the bundled data no longer matches the spec
+```
+
+CI runs the drift check, so a released package can not silently fall behind the API.
+
+## Development
+
+```bash
+npm install
+npm run build
+npm test
+```