@martin4455/redmine-mcp-ro 0.3.0

package/CONFIG.md

@@ -0,0 +1,242 @@
+# Local configuration and system credentials
+
+Version 0.3.0 stores a complete connection JSON in the operating system credential
+store. The local configuration uses format `3.0` and holds references and optional
+request limits and download settings. The package version, local file format and
+protected JSON version are independent values.
+
+## Select a directory
+
+```bash
+redmine-mcp configure --config-dir /absolute/path/to/project
+redmine-mcp-ro --config-dir /absolute/path/to/project
+```
+
+The directory must already exist. Selection uses `--config-dir`, then
+`REDMINE_CONFIG_DIR`, then the current working directory. There is no parent or
+home search, global fallback or `--global` option. To use a former home configuration,
+select that directory explicitly. Multiple clients can select the same directory.
+
+For a source checkout, build first and replace `redmine-mcp` with `node dist/cli.js`
+and `redmine-mcp-ro` with `node dist/index.js`. On Windows use a path such as
+`C:\projects\example`; inside JSON escape it as `C:\\projects\\example`.
+
+The application does not read `.env`. `REDMINE_URL` and `REDMINE_API_KEY` are not
+configuration sources. Use `configure` to set or change a connection.
+
+## Local file format
+
+```json
+{
+  "version": "3.0",
+  "defaultProfile": "default",
+  "profiles": {
+    "default": {
+      "credentialId": "08a93a80-42bc-4c88-a7d9-a10c24985de3"
+    }
+  },
+  "settings": {
+    "requestTimeoutMs": 30000,
+    "maxAttachmentBytes": 52428800,
+    "maxContentBytes": 5242880
+  }
+}
+```
+
+`settings` is optional. A profile accepts only `credentialId`. Adding `url`,
+`apiKey` or other unknown fields is rejected. Profile names, UUIDs and limits remain
+visible on disk. The example UUID above is a placeholder, not a working credential.
+
+New profile names contain 1-64 ASCII letters, digits, dots, underscores or hyphens,
+starting with a letter or digit; `constructor` and `prototype` are reserved.
+
+A UUID identifies an entry; it does not contain or decrypt its secret. The system
+store uses service `@martin4455/redmine-mcp-ro` and the UUID as the entry account.
+The secret value has this shape (example values only):
+
+```json
+{
+  "version": 1,
+  "url": "https://redmine.example.com",
+  "apiKey": "EXAMPLE_ONLY_REPLACE_WITH_YOUR_TOKEN"
+}
+```
+
+Both URL and token are read from that protected value. The URL cannot be overridden
+by local metadata or environment credentials. A reference does not isolate programs
+running under the same OS account; access is governed by the system store.
+Tokens and URLs are present in process memory during use. Redmine itself may return
+URLs and personal data as ordinary API content.
+
+## Platform setup
+
+| Platform | Store and requirements |
+| --- | --- |
+| macOS | Login Keychain. Unlock it and allow the Node.js executable when prompted. |
+| Windows | Credential Manager under the account running MCP. |
+| Linux / Ubuntu | Secret Service, such as GNOME Keyring, unlocked in the same user D-Bus session. |
+
+The adapter uses pinned `@napi-rs/keyring` 2.1.0 and native APIs, without shell
+commands containing credentials. Linux explicitly selects `secret-service`, so
+there is no kernel-keyring or file fallback. Locked, denied or unavailable stores
+cause an error. Native optional dependencies for the target platform must be installed.
+
+Ubuntu Desktop normally provides GNOME Keyring. Where it is absent, install it
+with `sudo apt install gnome-keyring dbus`. SSH, Docker and CI require an explicitly
+provisioned and unlocked Secret Service in the session used by the launcher.
+Preserve `DBUS_SESSION_BUS_ADDRESS` and the relevant `XDG_RUNTIME_DIR`. The isolated
+Ubuntu test harness is an example for synthetic test data, not a persistent vault.
+
+Windows Credential Manager limits the credential value to 2560 bytes. This adapter
+checks the UTF-16 size of the complete JSON before writing, including the URL, token,
+field names and escaping. An oversized value fails without a plaintext fallback.
+WSL uses the Linux backend, not Windows Credential Manager.
+
+Configure and run under the same OS account. A service account or another machine
+requires its own accessible credential store.
+
+## Configure, inspect and rotate
+
+```bash
+redmine-mcp configure --profile default --config-dir /path/to/project
+redmine-mcp list --config-dir /path/to/project
+redmine-mcp status --profile default --config-dir /path/to/project
+redmine-mcp use default --config-dir /path/to/project
+redmine-mcp remove default --config-dir /path/to/project
+```
+
+`configure` masks token input. The URL is shown in its interactive prompt, including
+as the default when updating an existing profile. The optional connection check
+reports success without printing a user's name. `list` reads metadata without
+accessing the keyring; `status` verifies access but displays neither URL nor token.
+
+For rotation, run `configure` again with the same profile and enter the new token.
+It creates a new UUID, writes the complete JSON, verifies exact read-back, commits
+the local file, then deletes the old entry. A failure before the file commit leaves
+the old configuration usable. Restart MCP to reload the credential held in memory.
+`remove` commits removal of the local reference before deleting the entry. Cleanup
+failures return a warning with the UUID and a nonzero exit code for manual removal.
+
+A copied file under the same OS account can refer to the same credential. Rotation
+or deletion invalidates that old reference in other copies. Prefer selecting one
+shared configuration directory or configuring independent profiles.
+
+Server profile selection uses `--profile`, then `REDMINE_PROFILE`, then
+`defaultProfile`, then the first profile. An unknown explicit selection is rejected.
+
+## Migration
+
+```bash
+redmine-mcp migrate --config-dir /path/to/project
+redmine-mcp status --config-dir /path/to/project
+```
+
+The server and ordinary CLI commands reject older formats until migration. The
+migration command supports:
+
+- Format `1.0`: plaintext URLs and tokens are written to new protected entries.
+- Format `2.0` with a URL and UUID: the existing protected JSON is checked against
+  the local URL, then the URL is removed from the local file. Existing entries in
+  the current service retain their UUIDs.
+- Format `2.0` with only a UUID: the current service is checked first. Only a missing
+  entry permits lookup in the historical `redmine-mcp-ro` service. Its complete JSON
+  is copied and verified under a new UUID in `@martin4455/redmine-mcp-ro`.
+
+A denied, locked or invalid current-store entry does not trigger fallback to another
+namespace. Historical entries are retained because other installations may use them.
+Migrating one copy does not update other files. Remove obsolete historical entries
+separately once no installation needs them.
+
+All profiles are validated before replacing the original file with format `3.0`.
+Legacy names outside the new naming rules are converted to unique valid names.
+Existing valid names are preserved; collisions receive numeric suffixes. The
+default profile follows its renamed entry, and the CLI prints each name mapping.
+Update explicit `--profile` or `REDMINE_PROFILE` selections to the reported name.
+Format `1.0` tokens have surrounding whitespace trimmed during migration; embedded
+line breaks and NUL bytes are rejected. URLs with embedded credentials, query
+strings or fragments still require manual correction, with a diagnostic identifying
+the profile by its position without printing the URL or token.
+
+Migration does not create a plaintext backup. On failure before the commit, the
+original file is retained and newly created entries are deleted where possible.
+Migration does not erase backups, Git history, copies or previously exposed data;
+rotate tokens that were exposed. Repeating migration on format `3.0` is a no-op.
+
+## File writes and limits
+
+Writes use a private temporary metadata file, flush it and rename it over the
+configuration. A lock and an original-content check prevent normal concurrent
+configurators from overwriting one another. Configuration symlinks, files larger
+than 1 MiB, unknown fields and duplicate UUID references are rejected. On POSIX,
+new metadata files have mode `0600`; on Windows, directory ACLs apply.
+
+The numeric `settings` keys accept positive safe integers. Environment settings take
+precedence over corresponding local settings; defaults apply if both are absent.
+
+| Local setting | Environment variable | Default |
+| --- | --- | --- |
+| `requestTimeoutMs` | `REDMINE_REQUEST_TIMEOUT_MS` | `30000` |
+| `maxAttachmentBytes` | `REDMINE_MAX_ATTACHMENT_BYTES` | `52428800` |
+| `maxContentBytes` | `REDMINE_MAX_CONTENT_BYTES` | `5242880` |
+| `downloadDir` | `REDMINE_DOWNLOAD_DIR` | Unset; local downloads disabled |
+
+Timeout cannot exceed `2147483647` ms. JSON API responses have a fixed 10 MiB limit.
+If no configurator is running but a previous process crashed, remove a stale
+`.redmine-mcp.lock` in the selected directory before retrying.
+
+## Local attachment downloads
+
+`download_attachment` and `download_issue_attachments` write local files and are
+marked accordingly in MCP tool annotations. They require an existing, dedicated
+download directory selected by the operator. For example, create
+`/absolute/path/to/redmine-downloads` and add `"downloadDir":
+"/absolute/path/to/redmine-downloads"` to `settings`, or set `REDMINE_DOWNLOAD_DIR`
+in the MCP launcher's environment. The environment value takes precedence. Paths
+must be absolute; `~` is not expanded. This setting is non-secret and visible on disk.
+
+Use a directory separate from source projects, home configuration and locations
+used to load scripts or other executable code. Downloaded content remains untrusted.
+The tool's optional `output_dir` accepts only a relative subdirectory such as
+`issue-123/documents`, using forward slashes. It defaults to the configured root,
+never the server's working directory. Missing subdirectories are created privately.
+Absolute paths, parent traversal, symlink subdirectories and dot-prefixed filenames
+are rejected. Existing files and symlinks are never overwritten. The root's canonical
+location is trusted; directory checks do not isolate a hostile process running as
+the same OS user and concurrently changing the filesystem.
+
+`get_attachment_content` returns bounded base64 content without filesystem writes
+and remains available without this setting.
+
+## Response filtering and diagnostics
+
+Both the API client and MCP boundary recursively remove structured API-key fields
+(`api_key`, `apiKey`, `api-key`, `X-Redmine-API-Key`, case-insensitively). Other user
+data, issue text and attachments are returned normally. This filter is not a general
+secret scanner. Earlier client history and tool results are not rewritten.
+
+Request errors exclude response bodies and request headers. Native errors are
+replaced with generic platform-specific guidance. API requests and redirects are
+restricted to the configured origin, including every redirect through a proxy.
+Redirect handling avoids `follow-redirects` request logging, so `DEBUG=*` and
+`DEBUG=follow-redirects` do not expose the API-key header. Use HTTPS outside isolated
+local tests.
+
+## Verification
+
+```bash
+npm run typecheck
+npm run lint
+npm test
+npm run test:keyring
+npm run test:keyring:ubuntu
+npm run test:integration
+docker compose -f test/docker-compose.test.yml down --volumes
+```
+
+Unit tests use test doubles for credentials. The native smoke test uses synthetic
+credentials, separate processes and a loopback HTTP fixture, then removes its test
+entries. Run it on each target OS, including Windows. The Ubuntu container also
+checks that an unavailable D-Bus session fails without fallback. The Redmine suite
+uses disposable Docker containers and an in-memory credential-store test double;
+it does not access the host keyring. With images already present, use
+`REDMINE_TEST_OFFLINE=1 npm run test:integration` to prohibit image pulls.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 martin4455
+
+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,196 @@
+# Redmine MCP Server (Read-Only)
+
+`@martin4455/redmine-mcp-ro` provides MCP tools for reading the Redmine REST API
+through the stdio transport. Version 0.3.0 stores the complete connection JSON,
+including the Redmine URL and API token, in the operating system credential store.
+
+## Requirements
+
+- Node.js 24.15 or later in the 24.x line, or Node.js 26 and later.
+- Redmine with its REST API enabled and an API key for the intended account.
+- An accessible macOS Keychain, Windows Credential Manager, or Linux Secret Service.
+
+Access to Redmine resources follows the permissions of the configured account.
+Some endpoints require administrator permissions.
+
+## Installation and configuration
+
+```bash
+npm install -g @martin4455/redmine-mcp-ro@0.3.0
+redmine-mcp configure --config-dir /absolute/path/to/project
+redmine-mcp status --config-dir /absolute/path/to/project
+```
+
+The selected directory must already exist. The configurator masks token input and
+can test the connection before saving. It stores `{version, url, apiKey}` together
+in the system credential store and verifies the saved value before committing the
+local reference. The URL appears in the interactive configuration prompt; `list`
+and `status` do not display the URL or token.
+
+The local `.redmine-mcp` file uses format `3.0` and contains profile names, random
+credential identifiers, and optional request limits and download settings. It contains neither the URL
+nor the API token. Configure and run MCP under the same OS account.
+
+On macOS, unlock the login Keychain and allow access for the Node.js executable
+when prompted. Windows uses Credential Manager for the account running MCP.
+Linux uses an unlocked Secret Service provider, such as GNOME Keyring, in the
+same user D-Bus session. A headless Linux process needs that session set up
+explicitly; see [platform setup](./CONFIG.md#platform-setup).
+
+Without `--config-dir`, configuration resolves from `REDMINE_CONFIG_DIR`, then the
+current working directory. There is no parent-directory or home-directory search.
+The server does not load `.env` and does not use `REDMINE_URL` or `REDMINE_API_KEY`.
+An unavailable system store stops the operation; there is no plaintext fallback.
+
+## Upgrade and token rotation
+
+Older local configuration formats `1.0` and `2.0` require explicit migration:
+
+```bash
+redmine-mcp migrate --config-dir /absolute/path/to/project
+redmine-mcp status --config-dir /absolute/path/to/project
+```
+
+Migration supports plaintext legacy profiles, profiles with a local URL and UUID,
+and the earlier reference-only format using service `redmine-mcp-ro`. It writes
+format `3.0` and uses service `@martin4455/redmine-mcp-ro`. Historical-service entries
+are retained because another local installation may still use them. No plaintext
+backup is created. Existing backups and copies are not erased.
+
+After rotating the token in Redmine, run `configure` for the existing profile and
+enter the replacement token. The command creates and verifies a new credential,
+commits the reference, then deletes the previous entry. Restart the MCP client to
+load the new connection. Copies of the old reference will need reconfiguration.
+
+```bash
+redmine-mcp configure --profile default --config-dir /absolute/path/to/project
+```
+
+See [CONFIG.md](./CONFIG.md) for the file format, platform setup and migration details.
+
+## MCP client configuration
+
+After configuring the directory, add a stdio server to your MCP client:
+
+```json
+{
+  "mcpServers": {
+    "redmine": {
+      "command": "redmine-mcp-ro",
+      "args": ["--config-dir", "/absolute/path/to/project"]
+    }
+  }
+}
+```
+
+Use an absolute executable path if the client does not inherit your terminal's
+PATH. A source checkout can use `node` with the absolute path to `dist/index.js`
+as the first argument. Windows JSON paths need escaped backslashes, for example
+`C:\\projects\\example`. No URL or token belongs in the MCP client's JSON.
+
+This package implements stdio. It does not provide an HTTP MCP server.
+
+## Profiles
+
+```bash
+redmine-mcp configure --profile staging --config-dir /absolute/path/to/project
+redmine-mcp list --config-dir /absolute/path/to/project
+redmine-mcp use staging --config-dir /absolute/path/to/project
+redmine-mcp-ro --profile staging --config-dir /absolute/path/to/project
+redmine-mcp remove staging --config-dir /absolute/path/to/project
+```
+
+Server profile selection uses `--profile`, then `REDMINE_PROFILE`, then the local
+default. An unknown explicitly selected profile fails rather than selecting another.
+`remove` deletes the selected profile and its corresponding credential.
+
+## Available tools
+
+| Resources | Tools |
+| --- | --- |
+| Issues | `list_issues`, `get_issue`, `list_issue_relations`, `get_relation` |
+| Projects | `list_projects`, `get_project`, `list_project_versions`, `get_version`, `list_project_memberships`, `get_membership`, `list_project_issue_categories`, `get_issue_category`, `list_project_files` |
+| Users and groups | `list_users`, `get_user`, `get_current_user`, `list_groups`, `get_group` |
+| Time entries | `list_time_entries`, `get_time_entry`, `list_time_entry_activities` |
+| Wiki and news | `list_wiki_pages`, `get_wiki_page`, `list_news` |
+| Metadata | `list_issue_statuses`, `list_trackers`, `list_issue_priorities`, `list_roles`, `get_role`, `list_custom_fields`, `list_queries` |
+| Search | `search` |
+| Attachments | `get_attachment`, `get_attachment_content`, `download_attachment`, `download_issue_attachments` |
+
+Local attachment downloads are disabled by default. To enable them, create a
+dedicated directory and set `REDMINE_DOWNLOAD_DIR` or `settings.downloadDir` to its
+absolute path. Use a directory for untrusted downloads, separate from source
+projects, home configuration and executable code. `output_dir` may select only a
+relative subdirectory; omitting it uses the configured root. Absolute paths, parent
+traversal, symlink subdirectories and dot-prefixed filenames are rejected. Existing
+files are never overwritten. `get_attachment_content` does not write files and
+does not require a download directory. See [CONFIG.md](./CONFIG.md#local-attachment-downloads).
+
+## Security behavior
+
+Structured API-key fields returned by Redmine are removed recursively in the API
+client and at the MCP output boundary. This includes `api_key`, `apiKey`, `api-key`
+and `X-Redmine-API-Key`, case-insensitively. Other Redmine data, including names,
+URLs, issue text and attachments, remains available as requested. The filter does
+not scan arbitrary text for secrets.
+
+Use HTTPS and an account with the permissions required for your use case. URLs
+with embedded credentials, query strings or fragments are rejected. API requests,
+attachments and redirects must remain on the configured origin. Downloaded filenames
+are validated against path traversal. Errors do not serialize request headers or
+response bodies. HTTP redirects use the native transport with explicit origin
+checks, so `DEBUG=*` and `DEBUG=follow-redirects` do not log the API-key header.
+
+Embedded attachment discovery ignores links outside the configured origin and
+does not execute document scripts or load remote HTML resources. Parser diagnostics
+containing document text are not forwarded to logs. Downloaded files are saved,
+never executed by this package; their contents remain untrusted.
+
+Default limits are 30 seconds per request, 50 MiB per downloaded file, 5 MiB for
+attachment content returned through MCP, and 10 MiB for JSON API responses. The
+first three can be changed through the documented local settings or environment
+variables in [CONFIG.md](./CONFIG.md).
+
+## Development and verification
+
+```bash
+npm ci --ignore-scripts
+npm run typecheck
+npm run lint
+npm test
+npm run build
+npm run check:package
+```
+
+The build cleans generated `dist/`, then compiles production TypeScript without
+source maps or test helpers. The npm archive contains compiled JavaScript, type
+declarations, `README.md`, `CONFIG.md`, `LICENSE` and `package.json`. The `prepack`
+script builds and checks this list automatically. There are no install lifecycle
+scripts in this package. Dependencies are installed according to normal npm rules.
+Direct runtime dependency versions are pinned. The repository lockfile fixes
+development and test installs; consumers can still resolve different transitive
+dependency versions within the dependencies' own ranges.
+
+Additional tests use synthetic credentials and disposable test resources:
+
+```bash
+npm run test:keyring
+npm run test:keyring:ubuntu
+npm run test:integration
+docker compose -f test/docker-compose.test.yml down --volumes
+```
+
+The native keyring test verifies persistence across processes, interactive CLI,
+MCP authentication, migration, rotation and cleanup. Run it on each target OS to
+verify native behavior. The Ubuntu test runs GNOME Keyring and D-Bus in Docker.
+The Redmine integration suite requires Docker and an accessible system store; use
+`REDMINE_TEST_PORT=18080` if port 8080 is occupied. Unit tests use test doubles for
+credential storage and local HTTP fixtures.
+
+## License and project links
+
+MIT; see [LICENSE](./LICENSE).
+
+- [Source repository](https://github.com/luskan/redmine-mcp)
+- [Issue tracker](https://github.com/luskan/redmine-mcp/issues)
+- [npm package](https://www.npmjs.com/package/@martin4455/redmine-mcp-ro)

package/dist/api-key-filter.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Redmine includes api_key in user responses for the account owner and admins.
+ * Remove these fields at every depth, including users embedded by extensions.
+ * This filters structured fields, not arbitrary secrets in issue text or files.
+ */
+export declare function stripApiKeys(value: unknown): unknown;

package/dist/api-key-filter.js

@@ -0,0 +1,16 @@
+const API_KEY_FIELD = /^(?:api[_-]?key|x-redmine-api-key)$/i;
+/**
+ * Redmine includes api_key in user responses for the account owner and admins.
+ * Remove these fields at every depth, including users embedded by extensions.
+ * This filters structured fields, not arbitrary secrets in issue text or files.
+ */
+export function stripApiKeys(value) {
+    if (Array.isArray(value))
+        return value.map(stripApiKeys);
+    if (value !== null && typeof value === 'object') {
+        return Object.fromEntries(Object.entries(value)
+            .filter(([key]) => !API_KEY_FIELD.test(key))
+            .map(([key, entry]) => [key, stripApiKeys(entry)]));
+    }
+    return value;
+}

package/dist/attachment-downloader.d.ts

@@ -0,0 +1,15 @@
+import type { AttachmentContent, AttachmentDownloadOptions, DownloadedAttachment, DownloadedIssueAttachment, RedmineConfig } from './types.js';
+export declare class AttachmentDownloader {
+    private readonly config;
+    private readonly client;
+    private readonly parser;
+    private readonly limits;
+    constructor(config: RedmineConfig);
+    private metadata;
+    private contentUrl;
+    downloadAttachment(attachmentId: number, outputDir?: string, options?: AttachmentDownloadOptions): Promise<DownloadedAttachment>;
+    private saveFile;
+    downloadIssueAttachments(issueId: number, outputDir?: string): Promise<DownloadedIssueAttachment[]>;
+    downloadAllIssueAttachments(issueId: number, outputDir?: string, includeEmbedded?: boolean): Promise<DownloadedIssueAttachment[]>;
+    getAttachmentContent(attachmentId: number): Promise<AttachmentContent>;
+}