@martin4455/redmine-mcp-ro 0.3.0 → 0.3.1

package/CONFIG.md

@@ -1,6 +1,6 @@
 # Local configuration and system credentials
 
-Version 0.3.0 stores a complete connection JSON in the operating system credential
+Since version 0.3.0, the server 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.

package/README.md

@@ -1,7 +1,12 @@
 # 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,
+through the stdio transport. Use it with Claude Code, Claude Desktop or Codex to
+read issues, inspect logs and screenshots attached to them, and compare issue
+requirements with your code or a pull request. Its Redmine operations are read-only:
+it does not create, edit or delete issues or other Redmine resources.
+
+Since version 0.3.0, the server stores the complete connection JSON,
 including the Redmine URL and API token, in the operating system credential store.
 
 ## Requirements
@@ -15,8 +20,50 @@ Some endpoints require administrator permissions.
 
 ## Installation and configuration
 
+### 1. Install the server
+
+Check that Node.js and npm are available, then install the latest release:
+
+```bash
+node -v
+npm -v
+npm install -g @martin4455/redmine-mcp-ro@latest
+```
+
+If Node.js is missing or outside the supported versions above, install a supported
+version from [nodejs.org](https://nodejs.org/en/download). You also need the MCP
+client you plan to use installed separately.
+
+The package installs two commands: `redmine-mcp` configures credentials, and
+`redmine-mcp-ro` runs the MCP server. The client launches the server for you;
+you do not need to keep a separate server terminal open.
+
+### 2. Configure Redmine in your project directory
+
+Replace the example path with an existing directory containing your project:
+
+If it already has a configuration from an older release, follow
+[Upgrade and token rotation](#upgrade-and-token-rotation) instead of configuring
+it again, then continue with step 3.
+
+```bash
+cd /absolute/path/to/project
+redmine-mcp configure
+redmine-mcp status
+```
+
+When prompted, choose a profile name (usually `default`), enter your Redmine base
+URL, such as `https://redmine.example.com`, and paste your API key. In standard
+Redmine, the key is on **My account** (`/my/account`), in the right-hand panel.
+In Easy Redmine, look in **Profile > Edit profile > API key**; labels can vary by
+installation. See [Redmine API authentication](https://www.redmine.org/projects/redmine/wiki/Rest_api#Authentication).
+Accept the optional connection test to check the URL and token against Redmine.
+`status` checks local configuration and credential-store access; it does not make
+a request to Redmine.
+
+You can select the same directory explicitly from any working directory:
+
 ```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
 ```
@@ -28,8 +75,9 @@ 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.
+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.
@@ -42,40 +90,62 @@ 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
+## MCP client configuration
 
-Older local configuration formats `1.0` and `2.0` require explicit migration:
+### 3. Add the server to your client
+
+Choose one of the following clients. Replace `/absolute/path/to/project` with the
+directory configured above; quote paths containing spaces. The explicit
+`--config-dir` makes configuration selection independent of the client's working
+directory. It selects a configuration file; it does not restrict which issues the
+Redmine account can read.
+
+#### Claude Code
+
+Run this from your project directory to add a server private to you in that project:
 
 ```bash
-redmine-mcp migrate --config-dir /absolute/path/to/project
-redmine-mcp status --config-dir /absolute/path/to/project
+cd /absolute/path/to/project
+claude mcp add --transport stdio --scope local redmine-local -- npx -y @martin4455/redmine-mcp-ro@latest --config-dir /absolute/path/to/project
+claude mcp list
 ```
 
-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.
+Start or restart `claude` in that project, then use `/mcp` to check the connection.
+The first `npx` launch may take longer while npm downloads the package.
+[Claude Code MCP documentation](https://code.claude.com/docs/en/mcp) explains the
+client's scopes and connection management.
 
-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.
+#### Codex CLI
 
 ```bash
-redmine-mcp configure --profile default --config-dir /absolute/path/to/project
+codex mcp add redmine-local -- npx -y @martin4455/redmine-mcp-ro@latest --config-dir /absolute/path/to/project
+codex mcp list
 ```
 
-See [CONFIG.md](./CONFIG.md) for the file format, platform setup and migration details.
+Start or restart `codex`, then use `/mcp` to inspect active servers. Codex normally
+stores this registration in `~/.codex/config.toml`, so adding it from a project
+directory does not make it exclusive to that project. For a project-specific
+registration, use the following in that project's `.codex/config.toml` instead of
+the `codex mcp add` command above; project configuration requires a trusted project:
 
-## MCP client configuration
+```toml
+[mcp_servers.redmine-local]
+command = "npx"
+args = ["-y", "@martin4455/redmine-mcp-ro@latest", "--config-dir", "/absolute/path/to/project"]
+```
 
-After configuring the directory, add a stdio server to your MCP client:
+See the [OpenAI MCP documentation](https://developers.openai.com/codex/mcp) for
+client configuration and scope details.
+
+#### Claude Desktop
+
+Open **Settings > Developer > Edit Config** and merge this entry into
+`claude_desktop_config.json`, preserving any existing servers:
 
 ```json
 {
   "mcpServers": {
-    "redmine": {
+    "redmine-local": {
       "command": "redmine-mcp-ro",
       "args": ["--config-dir", "/absolute/path/to/project"]
     }
@@ -83,13 +153,98 @@ After configuring the directory, add a stdio server to your MCP client:
 }
 ```
 
-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 uses the global installation from step 1. Fully quit and reopen Claude
+Desktop after saving. See the [local MCP setup guide](https://modelcontextprotocol.io/docs/develop/connect-local-servers)
+for the configuration editor and troubleshooting.
+
+If the client cannot find the executable, locate it with `command -v redmine-mcp-ro`
+on macOS/Linux or `where.exe redmine-mcp-ro` on Windows and use its absolute path.
+Windows JSON paths need escaped backslashes, for example `C:\\projects\\example`.
+On Windows, a client that cannot directly launch an npm `.cmd` shim can use
+`"command": "cmd"` with arguments starting `["/c", "redmine-mcp-ro", ...]`.
+No URL or token belongs in the MCP client's JSON.
+
+After a global installation, the CLI examples can also launch `redmine-mcp-ro`
+directly: replace `npx -y @martin4455/redmine-mcp-ro@latest` with `redmine-mcp-ro`.
+To keep an exact release in an `npx` configuration, replace `@latest` with `@0.3.1`.
+A source checkout can use `node` with the absolute path to `dist/index.js` as the
+first argument.
 
 This package implements stdio. It does not provide an HTTP MCP server.
 
+### 4. Enable attachment downloads if needed
+
+Reading issue text and fetching bounded attachment content works immediately.
+Saving attachments to disk requires an explicit download directory in 0.3.0.
+Create a dedicated directory outside your source project, for example
+`/absolute/path/to/redmine-downloads`. In the project's `.redmine-mcp`, merge this
+top-level `settings` member, keeping your existing `profiles`, `defaultProfile`,
+`version` and other settings:
+
+```json
+{
+  "settings": {
+    "downloadDir": "/absolute/path/to/redmine-downloads"
+  }
+}
+```
+
+This is a settings fragment, not a replacement for the whole configuration file.
+Alternatively, set `REDMINE_DOWNLOAD_DIR` in the MCP server's launch environment.
+Restart the MCP client after changing the setting. Tool calls may choose a relative
+subdirectory such as `issue-12345`; absolute `output_dir` values are rejected.
+See [attachment download settings](./CONFIG.md#local-attachment-downloads).
+
+### 5. Check the connection and analyze an issue
+
+In a new client session, ask:
+
+> Use the redmine-local MCP server to fetch my current Redmine user and confirm
+> that the connection works. Do not display any API keys.
+
+Then try an issue you can access:
+
+> Read Redmine issue 12345 and inspect its description, comments and attachments.
+> Analyze the logs and screenshots, compare them with the code in this project,
+> diagnose the problem and propose a fix.
+
+Or ask for a review:
+
+> Compare this pull request with the requirements in Redmine issue 12345.
+> Identify missing behavior, regressions and tests that should be added.
+
+The server retrieves issue data and attachment bytes. Image viewing, unpacking
+archives, inspecting local source files and reviewing pull requests use the MCP
+client's other tools and permissions. The server itself does not unpack archives
+or execute downloaded files.
+
+## Upgrade and token rotation
+
+Older local configuration formats `1.0` and `2.0` require explicit migration:
+
+```bash
+npm install -g @martin4455/redmine-mcp-ro@latest
+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.
+
 ## Profiles
 
 ```bash
@@ -183,9 +338,10 @@ 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.
+The Redmine integration suite requires Docker and uses a credential-store test
+double; it does not access the host keyring. 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
 

package/dist/cli.js

@@ -93,7 +93,7 @@ async function configure(options) {
     }
     report(await manager.configure(profileName, answers.url, answers.apiKey), `Profile reference saved to ${manager.configPath}. URL and API key stored together in the system credential store.`);
 }
-const program = new Command().name('redmine-mcp').description('Configure local Redmine profiles using the system credential store').version('0.3.0');
+const program = new Command().name('redmine-mcp').description('Configure local Redmine profiles using the system credential store').version('0.3.1');
 const command = (name, description) => program.command(name).description(description)
     .option('-d, --config-dir <directory>', 'Directory containing .redmine-mcp (default: REDMINE_CONFIG_DIR or current directory)');
 command('configure', 'Save the connection JSON in the system credential store')

package/dist/index.js

@@ -6,7 +6,7 @@ import { startServer } from './server.js';
 const program = new Command()
     .name('redmine-mcp-ro')
     .description('Read-only Redmine MCP server using a local configuration and system credential store')
-    .version('0.3.0')
+    .version('0.3.1')
     .option('-d, --config-dir <directory>', 'Directory containing .redmine-mcp (default: REDMINE_CONFIG_DIR or current directory)')
     .option('-p, --profile <name>', 'Local profile (default: REDMINE_PROFILE or configured default)')
     .parse();

package/dist/server.js

@@ -21,7 +21,7 @@ export async function startServer(redmineConfig) {
     // Create MCP server
     const server = new Server({
         name: 'redmine-mcp-ro',
-        version: '0.3.0',
+        version: '0.3.1',
     }, {
         capabilities: {
             tools: {},

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@martin4455/redmine-mcp-ro",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Model Context Protocol server for read-only access to Redmine REST API",
   "main": "dist/index.js",
   "type": "module",