@kontexted/mcp-cli 0.1.0 → 0.1.1

package/README.md

@@ -0,0 +1,346 @@
+# Kontexted MCP CLI
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+**MCP client and proxy for connecting AI assistants to Kontexted.**
+
+The Kontexted MCP CLI bridges AI coding assistants (opencode, Claude Code, etc.) with your Kontexted instance. It handles authentication, profile management, and translates MCP requests to your Kontexted server's API.
+
+---
+
+## What is this?
+
+The [Kontexted](https://github.com/kontexted/kontexted) server provides an MCP (Model Context Protocol) endpoint that allows AI assistants to query your notes. Since Kontexted is open source, you can host multiple instances for different teams or environments, and each instance contains multiple workspaces.
+
+This CLI helps you manage these scenarios by:
+
+- **OAuth 2.0 Authentication** - Handles full OAuth flow with PKCE code verifier
+- **Profile Management** - Store and switch between multiple Kontexted instances and workspaces
+- **Workspace Scoping** - Narrows the LLM's context to a single workspace per profile
+- **MCP Proxy Server** - Translates MCP stdio requests to HTTP calls to Kontexted
+- **Tool Filtering** - Injects workspace context and controls write access per-profile
+
+---
+
+## Installation
+
+### Prerequisites
+
+- Kontexted server running at your instance
+
+### Using npx / bunx (Recommended)
+
+The easiest way to run Kontexted MCP CLI without installing:
+
+```bash
+# Using bunx
+bunx @kontexted/mcp-cli
+
+# Using npx
+npx @kontexted/mcp-cli
+```
+
+No installation required - just replace `kontexted-mcp` with `bunx @kontexted/mcp-cli` or `npx @kontexted/mcp-cli` in all examples below.
+
+### Global Install (Optional)
+
+If you prefer a shorter command, install globally:
+
+```bash
+bun install -g @kontexted/mcp-cli
+```
+
+Then run directly:
+
+```bash
+kontexted-mcp
+```
+
+---
+
+## Usage
+
+### 1. Login
+
+Authenticate with your Kontexted instance and store a profile:
+
+```bash
+kontexted-mcp login --url <mcp-server-url> --workspace <workspace-slug>
+```
+
+**Required flags:**
+- `--url`: MCP server URL (e.g., `http://localhost:3000/api/mcp` or `https://app.example.com/api/mcp`)
+- `--workspace`: Workspace slug from your Kontexted instance
+
+**Optional flags:**
+- `--alias <name>`: Store profile under a custom name (defaults to workspace name)
+- `--write`: Enable write operations (create folders/notes) for this profile
+
+**Examples:**
+
+```bash
+# Login to local development instance
+kontexted-mcp login --url http://localhost:3000/api/mcp --workspace my-project
+
+# Login to production with alias
+kontexted-mcp login --url https://app.mycompany.com/api/mcp --workspace my-project --alias prod
+
+# Login with write access enabled
+kontexted-mcp login --url http://localhost:3000/api/mcp --workspace my-project --write
+```
+
+**What happens during login:**
+
+1. CLI starts a temporary local HTTP server on port 8788
+2. Opens your browser to Kontexted's OAuth authorization page
+3. You sign in with Keycloak and authorize the MCP client
+4. Kontexted redirects to the callback URL with an authorization code
+5. CLI exchanges the code for access and refresh tokens
+6. Tokens and client information are stored in `~/.kontexted/mcp.json`
+
+---
+
+### 2. View Stored Profiles
+
+Show all configured profiles:
+
+```bash
+kontexted-mcp show-config
+```
+
+Output example:
+
+```json
+{
+  "profiles": {
+    "my-project": {
+      "serverUrl": "http://localhost:3000/api/mcp",
+      "workspace": "my-project",
+      "write": false,
+      "oauth": {
+        "tokens": { "...": "..." },
+        "codeVerifier": "...",
+        "clientInformation": { "...": "..." }
+      }
+    },
+    "prod": {
+      "serverUrl": "https://app.mycompany.com/api/mcp",
+      "workspace": "my-project",
+      "write": true,
+      "oauth": { "...": "..." }
+    }
+  }
+}
+```
+
+---
+
+### 3. Start MCP Proxy Server
+
+Run the MCP proxy server (default command when no subcommand is provided):
+
+```bash
+kontexted-mcp [--alias <name> | --workspace <slug>] [--write | --write-off]
+```
+
+**Required flags (one or the other):**
+- `--alias <name>`: Use profile by alias
+- `--workspace <slug>`: Find profile by workspace name
+
+**Optional flags:**
+- `--write`: Override profile to enable write operations
+- `--write-off`: Override profile to disable write operations
+
+**Examples:**
+
+```bash
+# Start with default read-only access
+kontexted-mcp --alias prod
+
+# Start with write access for this session only
+kontexted-mcp --alias my-project --write
+
+# Start using workspace name instead of alias
+kontexted-mcp --workspace my-project
+```
+
+The CLI will:
+1. Load the specified profile from `~/.kontexted/mcp.json`
+2. Connect to Kontexted's MCP server using stored tokens
+3. List available tools and register them with MCP stdio transport
+4. Remove `workspaceSlug` from tool input schemas (injected automatically)
+5. Filter out write tools unless `--write` is specified
+6. Wait for MCP requests from your AI assistant
+
+---
+
+### 4. Logout
+
+Remove one or all stored profiles:
+
+```bash
+# Remove specific profile by alias
+kontexted-mcp logout --alias prod
+
+# Remove specific profile by workspace
+kontexted-mcp logout --workspace my-project
+
+# Remove all profiles
+kontexted-mcp logout
+```
+
+---
+
+## Integrating with opencode
+
+The Kontexted MCP CLI is designed to work as an MCP server that can be configured in opencode.
+
+### Step 1: Add MCP Server to opencode.json
+
+Edit your project's `opencode.json`:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "kontexted": {
+      "type": "local",
+      "enabled": true,
+      "command": ["kontexted-mcp", "--alias", "prod"],
+    }
+  }
+}
+```
+
+Replace `--alias` with your profile name or use `--workspace` instead.
+
+### Step 2: Configure Write Access (Optional)
+
+If you want opencode to create notes or folders in Kontexted:
+
+1. Enable write access during login: `kontexted-mcp login --url <url> --workspace <slug> --write`
+2. Or override per-session: `"args": ["--alias", "prod", "--write"]`
+
+### Step 3: Restart opencode
+
+Restart your opencode session to load the MCP server.
+
+### Step 4: Use Kontexted Tools
+
+opencode can now access Kontexted MCP tools:
+
+- `getWorkspaceTree` - Fetch workspace structure (folders and notes)
+- `searchNotesByQuery` - Search notes by name or title
+- `getNoteById` - Retrieve a specific note's content
+- `createFolder` - Create a new folder (requires `--write`)
+- `createNote` - Create a new note (requires `--write`)
+
+The CLI automatically injects your configured `workspaceSlug` into all requests, so you don't need to specify it manually.
+
+---
+
+## Tool Filtering
+
+The CLI filters MCP tools based on your profile's write settings:
+
+| Tool | Read-Only | With Write |
+|-------|------------|------------|
+| `getWorkspaceTree` | ✅ | ✅ |
+| `searchNotesByQuery` | ✅ | ✅ |
+| `getNoteById` | ✅ | ✅ |
+| `createFolder` | ❌ | ✅ |
+| `createNote` | ❌ | ✅ |
+
+By default, profiles are created in read-only mode. Use `--write` during login or session start to enable write operations.
+
+---
+
+## Configuration File
+
+Profiles are stored in:
+
+```
+~/.kontexted/mcp.json
+```
+
+Each profile contains:
+- `serverUrl`: Kontexted MCP server URL
+- `workspace`: Workspace slug
+- `write`: Default write access setting
+- `oauth.tokens`: OAuth access and refresh tokens
+- `oauth.codeVerifier`: PKCE code verifier for token refresh
+- `oauth.clientInformation`: OAuth client metadata
+
+**Security Note:** Tokens are stored in plain text on disk. Ensure your system's `~/.kontexted` directory has appropriate permissions.
+
+---
+
+## Troubleshooting
+
+### "Unauthorized. Run 'kontexted-mcp login' first."
+
+Your tokens have expired or are missing. Run login again:
+
+```bash
+kontexted-mcp login --url <url> --workspace <workspace>
+```
+
+The CLI will automatically refresh expired tokens when possible.
+
+### "Failed to open browser"
+
+The CLI couldn't automatically open your browser. Copy the URL from your terminal and open it manually.
+
+### Port 8788 already in use
+
+The OAuth callback server requires port 8788. If it's occupied:
+
+1. Close other processes using the port, or
+2. Manually copy the authorization URL from the CLI output
+
+### Profile not found
+
+Check your stored profiles:
+
+```bash
+kontexted-mcp show-config
+```
+
+Use the exact alias or workspace name shown in the output.
+
+---
+
+## Development
+
+For contributing or running from source code:
+
+```bash
+# Clone repository
+git clone https://github.com/kontexted/kontexted-mcp-cli.git
+cd kontexted-mcp-cli
+
+# Install dependencies
+bun install
+
+# Run from source
+bun run start
+
+# Build distribution
+bun run build
+```
+
+**Note:** Building from source is only necessary for development. For regular use, run with `bunx` or `npx` instead.
+
+---
+
+## License
+
+[MIT License](LICENSE) - Copyright (c) 2026 Rabbyte
+
+---
+
+## Links
+
+- [Kontexted Server](https://github.com/kontexted/kontexted) - Main Kontexted application
+- [Issues & Bug Reports](https://github.com/kontexted/kontexted-mcp-cli/issues)
+- [Model Context Protocol](https://modelcontextprotocol.io/) - MCP specification

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontexted/mcp-cli",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "type": "module",
   "repository": {
     "type": "git",