@blackenedd18/planio-connector 2026.623.2

package/.env.example

@@ -0,0 +1,9 @@
+# Required: Redmine/Planio API key (or pass via --api-key argument)
+REDMINE_API_KEY=
+
+# Required: Planio / Redmine instance base URL, no trailing slash
+# (or pass via --redmine-url argument)
+REDMINE_URL=https://your-redmine.example.com
+
+# Optional: debug | info | warn | error
+LOG_LEVEL=debug

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 blackenedd18
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,101 @@
+# @blackenedd18/planio-connector
+
+> Node.js MCP server that exposes Planio/Redmine operations over stdio.
+
+[![npm](https://img.shields.io/npm/v/@blackenedd18/planio-connector.svg)](https://www.npmjs.com/package/@blackenedd18/planio-connector)
+
+`@blackenedd18/planio-connector` is a ready-to-run MCP server powered by
+`@modelcontextprotocol/sdk`. It provides tool-based access to users, issues, projects,
+hours, and time entries against a Planio/Redmine REST API.
+
+## Why Use It
+
+- You need Redmine operations exposed as MCP tools for LLM hosts.
+- You want a modular Node.js MCP implementation that is easy to extend by domain.
+- You want a single `npx` command to run it with no global install.
+
+## Install & Run (npx)
+
+Run the published package directly — no install required:
+
+```bash
+npx -y @blackenedd18/planio-connector --api-key <YOUR_REDMINE_API_KEY> --redmine-url <YOUR_REDMINE_URL>
+```
+
+Or install globally and run the `planio-connector` binary:
+
+```bash
+npm install -g @blackenedd18/planio-connector
+planio-connector --api-key <YOUR_REDMINE_API_KEY> --redmine-url <YOUR_REDMINE_URL>
+```
+
+## Local Development
+
+```bash
+npm install
+REDMINE_API_KEY=test_key REDMINE_URL=https://your-redmine.example.com npm start
+```
+
+Run directly with npx from the source checkout:
+
+```bash
+npx . --api-key test_key --redmine-url https://your-redmine.example.com
+```
+
+## Key Features
+
+- **MCP-native tool server** — stdio transport with typed MCP request handlers.
+- **Domain modules** — users, issues, projects, hours, and time entries.
+- **Stable response shapes** — request pipeline normalizes outputs for MCP compatibility.
+- **Local function adapter** — no outbound HTTP required for built-in handler mode.
+- **Regression test suite** — `node:test` coverage for adapter and response contracts.
+
+## Example
+
+Use it in an MCP host:
+
+```json
+{
+  "mcpServers": {
+    "planio-connector": {
+      "command": "npx",
+      "args": [
+        "-y", "@blackenedd18/planio-connector",
+        "--api-key", "${REDMINE_API_KEY}",
+        "--redmine-url", "${REDMINE_URL}"
+      ]
+    }
+  }
+}
+```
+
+## Requirements
+
+- Node.js >= 18
+- `REDMINE_API_KEY` via env var or `--api-key`
+- `REDMINE_URL` via env var or `--redmine-url` — Planio/Redmine base URL
+
+## Common Scripts
+
+| Command | Purpose |
+|---------|---------|
+| `npm start` | Start MCP server from `src/index.js` |
+| `npm run start:npx` | Start via package npx entry |
+| `npm test` | Run regression and compatibility tests |
+| `npm run inspector` | Open MCP inspector workflow |
+
+---
+
+## Documentation
+
+| Guide | Description |
+|-------|-------------|
+| [Getting Started](docs/getting-started.md) | Install, run, and verify the server |
+| [Architecture](docs/architecture.md) | Module boundaries and data flow |
+| [Configuration](docs/configuration.md) | Environment variables and runtime settings |
+| [CLI Usage](docs/cli.md) | Available npm and npx commands |
+| [MCP Tools](docs/mcp-tools.md) | Domain tool catalog and examples |
+
+## License
+
+ISC

package/Redmine-functions/README.md

@@ -0,0 +1,14 @@
+# Redmine-functions
+
+Local function handlers used by the Node.js MCP server instead of outbound HTTP API calls.
+
+## Contract
+
+- Entry function: `executeRequest({ method, endpoint, params, body, apiKey })`
+- Returns plain JavaScript data for the requested endpoint
+- Throws `Error` with optional `status` for unsupported handlers or invalid input
+
+## Notes
+
+- This module is intentionally local-function based (`no-network` runtime path)
+- Add or adjust handlers in `index.js` when new MCP tools/endpoints are introduced