{"_id":"@alminni/mcp-server","_rev":"4-80579638407fc3ddc132fa57fb6e0d06","name":"@alminni/mcp-server","dist-tags":{"latest":"0.14.0"},"versions":{"0.13.0":{"name":"@alminni/mcp-server","version":"0.13.0","keywords":["cli","alminni","ai","knowledge-management","development-tools"],"author":{"name":"Julius Biskur","email":"julius@flowcore.io"},"license":"MIT","_id":"@alminni/mcp-server@0.13.0","maintainers":[{"name":"jbiskur","email":"jbiskur@gmail.com"}],"homepage":"https://github.com/flowcore-io/alminni-mcp#readme","bugs":{"url":"https://github.com/flowcore-io/alminni-mcp/issues"},"bin":{"alminni-mcp":"dist/cli/index.js"},"dist":{"shasum":"5868a8f8cfa74204c152e4fe1892563ed15e3336","tarball":"https://registry.npmjs.org/@alminni/mcp-server/-/mcp-server-0.13.0.tgz","fileCount":4,"integrity":"sha512-i+gPBLLAgrHmv2YvK4TcDcPfTNm0oFxUm1ffP6MmT30GhdSm7ysUXEC3H8QljJsbxjL5SayzO6rXC1dEig8VkA==","signatures":[{"sig":"MEYCIQDDLkb5JhUP0V4GKAgfRCV+ao8bvyr/3Y7YsiD9zllycwIhANOt8aipunjU1dZfjqskLeQNlmy3tJIZItaxrRsY1wnP","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":647457},"type":"module","engines":{"node":">=18.0.0"},"gitHead":"ccb829aef06734d743185b27372ccee83f64e937","scripts":{"lint":"biome check src/","test":"bun test","build":"bun build src/cli/index.ts --outdir=dist/cli --target=node --format=esm && chmod +x dist/cli/index.js","format":"biome format src/ --write","dev:cli":"bun run src/cli/index.ts","test:ci":"bun test --coverage --timeout 30000","lint:fix":"biome check src/ --write","test:cli":"bun test tests/cli","test:debug":"bun test --verbose","test:watch":"bun test --watch","type-check":"tsc --noEmit","build:watch":"bun build src/cli/index.ts --outdir=dist/cli --target=node --format=esm --watch","publish:beta":"npm publish --tag beta","test:coverage":"bun test --coverage","prepublishOnly":"bun run build","publish:latest":"npm publish"},"_npmUser":{"name":"jbiskur","email":"jbiskur@gmail.com"},"repository":{"url":"git+https://github.com/flowcore-io/alminni-mcp.git","type":"git"},"_npmVersion":"10.8.1","description":"Alminni CLI - Configure AI-powered knowledge management for development teams","directories":{},"_nodeVersion":"20.16.0","dependencies":{"zod":"^3.25.67","dotenv":"^16.5.0","commander":"^14.0.0","@modelcontextprotocol/sdk":"^1.13.1"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"msw":"^2.10.2","@types/bun":"^1.2.17","typescript":"^5.8.3","@types/node":"^24.0.3","@biomejs/biome":"^2.0.0"},"peerDependencies":{"typescript":"^5"},"_npmOperationalInternal":{"tmp":"tmp/mcp-server_0.13.0_1756827795319_0.8437914271935012","host":"s3://npm-registry-packages-npm-production"}},"0.13.1":{"name":"@alminni/mcp-server","version":"0.13.1","keywords":["cli","alminni","ai","knowledge-management","development-tools"],"author":{"name":"Julius Biskur","email":"julius@flowcore.io"},"license":"MIT","_id":"@alminni/mcp-server@0.13.1","maintainers":[{"name":"jbiskur","email":"jbiskur@gmail.com"}],"homepage":"https://github.com/flowcore-io/alminni-mcp#readme","bugs":{"url":"https://github.com/flowcore-io/alminni-mcp/issues"},"bin":{"alminni-mcp":"dist/cli/index.js"},"dist":{"shasum":"05bf3128c31b5b238550f7bffe7b4b35f234215c","tarball":"https://registry.npmjs.org/@alminni/mcp-server/-/mcp-server-0.13.1.tgz","fileCount":4,"integrity":"sha512-eXjJ1lCuFuCnFEs0NzLNxvl7Z4nMr5+M1MKcMgXzMEy2HTsVV45TRxW1u7PaY9PHemI7sn6ARDltgotvg4Os7A==","signatures":[{"sig":"MEUCIQDvqfN49Xnvn41OsJkrNBsWGHuG+9ZykQir6Q1MXipwqwIgFvu09Lt57wpTIGyvWh6FPZvRKK6GkZc3WmbgJQcaaFk=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":647468},"type":"module","engines":{"node":">=18.0.0"},"gitHead":"0fac1aa20512a6bb607185829937d9c577e1c4e4","scripts":{"lint":"biome check src/","test":"bun test","build":"bun build src/cli/index.ts --outdir=dist/cli --target=node --format=esm && chmod +x dist/cli/index.js","format":"biome format src/ --write","dev:cli":"bun run src/cli/index.ts","test:ci":"bun test --coverage --timeout 30000","lint:fix":"biome check src/ --write","test:cli":"bun test tests/cli","test:debug":"bun test --verbose","test:watch":"bun test --watch","type-check":"tsc --noEmit","build:watch":"bun build src/cli/index.ts --outdir=dist/cli --target=node --format=esm --watch","publish:beta":"npm publish --tag beta","test:coverage":"bun test --coverage","prepublishOnly":"bun run build","publish:latest":"npm publish"},"_npmUser":{"name":"jbiskur","email":"jbiskur@gmail.com"},"repository":{"url":"git+https://github.com/flowcore-io/alminni-mcp.git","type":"git"},"_npmVersion":"10.8.1","description":"Alminni CLI - Configure AI-powered knowledge management for development teams","directories":{},"_nodeVersion":"20.16.0","dependencies":{"zod":"^3.25.67","dotenv":"^16.5.0","commander":"^14.0.0","@modelcontextprotocol/sdk":"^1.13.1"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"msw":"^2.10.2","@types/bun":"^1.2.17","typescript":"^5.8.3","@types/node":"^24.0.3","@biomejs/biome":"^2.0.0"},"peerDependencies":{"typescript":"^5"},"_npmOperationalInternal":{"tmp":"tmp/mcp-server_0.13.1_1756830104043_0.7286711686699368","host":"s3://npm-registry-packages-npm-production"}},"0.13.2":{"name":"@alminni/mcp-server","version":"0.13.2","keywords":["cli","alminni","ai","knowledge-management","development-tools"],"author":{"name":"Julius Biskur","email":"julius@flowcore.io"},"license":"MIT","_id":"@alminni/mcp-server@0.13.2","maintainers":[{"name":"jbiskur","email":"jbiskur@gmail.com"}],"homepage":"https://github.com/flowcore-io/alminni-mcp#readme","bugs":{"url":"https://github.com/flowcore-io/alminni-mcp/issues"},"bin":{"alminni-mcp":"dist/cli/index.js"},"dist":{"shasum":"cad556dca0818e1d769bf61300cff41814c99c10","tarball":"https://registry.npmjs.org/@alminni/mcp-server/-/mcp-server-0.13.2.tgz","fileCount":4,"integrity":"sha512-M+ca1QAaGkE7vGvDEUGSNHBYgECKld7Ug7JUfuG+1W5NetJ5KPMJd9ngqYRrjvZKWOkM3oyr/3jdnMpCnitzBA==","signatures":[{"sig":"MEUCIQDdm7BjlXyg9yA6bUIzmFtZdptgnlGVuF6NVGv4+gIT1wIgamiLQEgSaDNUKDr5hTLDGka0yKYzr8vFrxH+JbRhgGU=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":647060},"type":"module","engines":{"node":">=18.0.0"},"gitHead":"4338abc77253005d72283caf1247db34a7d8837a","scripts":{"lint":"biome check src/","test":"bun test","build":"bun build src/cli/index.ts --outdir=dist/cli --target=node --format=esm && chmod +x dist/cli/index.js","format":"biome format src/ --write","dev:cli":"bun run src/cli/index.ts","test:ci":"bun test --coverage --timeout 30000","lint:fix":"biome check src/ --write","test:cli":"bun test tests/cli","test:debug":"bun test --verbose","test:watch":"bun test --watch","type-check":"tsc --noEmit","build:watch":"bun build src/cli/index.ts --outdir=dist/cli --target=node --format=esm --watch","publish:beta":"npm publish --tag beta","test:coverage":"bun test --coverage","prepublishOnly":"bun run build","publish:latest":"npm publish"},"_npmUser":{"name":"jbiskur","email":"jbiskur@gmail.com"},"repository":{"url":"git+https://github.com/flowcore-io/alminni-mcp.git","type":"git"},"_npmVersion":"10.8.1","description":"Alminni CLI - Configure AI-powered knowledge management for development teams","directories":{},"_nodeVersion":"20.16.0","dependencies":{"zod":"^3.25.67","dotenv":"^16.5.0","commander":"^14.0.0","@modelcontextprotocol/sdk":"^1.13.1"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"msw":"^2.10.2","@types/bun":"^1.2.17","typescript":"^5.8.3","@types/node":"^24.0.3","@biomejs/biome":"^2.0.0"},"peerDependencies":{"typescript":"^5"},"_npmOperationalInternal":{"tmp":"tmp/mcp-server_0.13.2_1757070026675_0.23774938478012064","host":"s3://npm-registry-packages-npm-production"}},"0.14.0":{"name":"@alminni/mcp-server","version":"0.14.0","description":"Alminni CLI - Configure AI-powered knowledge management for development teams","type":"module","bin":{"alminni-mcp":"dist/cli/index.js"},"publishConfig":{"access":"public"},"scripts":{"dev:cli":"bun run src/cli/index.ts","build":"bun build src/cli/index.ts --outdir=dist/cli --target=node --format=esm && chmod +x dist/cli/index.js","build:watch":"bun build src/cli/index.ts --outdir=dist/cli --target=node --format=esm --watch","test":"bun test","test:cli":"bun test tests/cli","test:watch":"bun test --watch","test:coverage":"bun test --coverage","test:ci":"bun test --coverage --timeout 30000","test:debug":"bun test --verbose","lint":"biome check src/","lint:fix":"biome check src/ --write","format":"biome format src/ --write","type-check":"tsc --noEmit","prepublishOnly":"bun run build","publish:beta":"npm publish --tag beta","publish:latest":"npm publish"},"devDependencies":{"@biomejs/biome":"^2.0.0","@types/bun":"^1.2.17","@types/node":"^24.0.3","msw":"^2.10.2","typescript":"^5.8.3"},"peerDependencies":{"typescript":"^5"},"dependencies":{"@modelcontextprotocol/sdk":"^1.13.1","commander":"^14.0.0","dotenv":"^16.5.0","zod":"^3.25.67"},"keywords":["cli","alminni","ai","knowledge-management","development-tools"],"author":{"name":"Julius Biskur","email":"julius@flowcore.io"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/flowcore-io/alminni-mcp.git"},"bugs":{"url":"https://github.com/flowcore-io/alminni-mcp/issues"},"homepage":"https://github.com/flowcore-io/alminni-mcp#readme","engines":{"node":">=18.0.0"},"_id":"@alminni/mcp-server@0.14.0","gitHead":"5778f15aa71f01f75244758cb59023b9d56f5722","_nodeVersion":"20.16.0","_npmVersion":"10.8.1","dist":{"integrity":"sha512-3QJUwL+YcF8giX+y05+yopBDIJOQE9GFYQIUnaG/xDgC/pnROIFuHMlwQASY6Z4qvhCUwfc64D0ISIBXlY91EA==","shasum":"311ba3dac19c198ea0f4123082f9b900cc29bd20","tarball":"https://registry.npmjs.org/@alminni/mcp-server/-/mcp-server-0.14.0.tgz","fileCount":4,"unpackedSize":656692,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDS10hzryKHBH5BD2Qd9pSUbtAV1a+/hJReRY8uIDboSgIgCI10HJepfduyF7GIwjyD1NivQmS7+xt3aDrOS6zFkws="}]},"_npmUser":{"name":"jbiskur","email":"jbiskur@gmail.com"},"directories":{},"maintainers":[{"name":"jbiskur","email":"jbiskur@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mcp-server_0.14.0_1758532259364_0.9404634752987084"},"_hasShrinkwrap":false}},"time":{"created":"2025-09-02T15:43:15.209Z","modified":"2025-09-22T09:10:59.810Z","0.13.0":"2025-09-02T15:43:15.526Z","0.13.1":"2025-09-02T16:21:44.249Z","0.13.2":"2025-09-05T11:00:26.894Z","0.14.0":"2025-09-22T09:10:59.580Z"},"bugs":{"url":"https://github.com/flowcore-io/alminni-mcp/issues"},"author":{"name":"Julius Biskur","email":"julius@flowcore.io"},"license":"MIT","homepage":"https://github.com/flowcore-io/alminni-mcp#readme","keywords":["cli","alminni","ai","knowledge-management","development-tools"],"repository":{"type":"git","url":"git+https://github.com/flowcore-io/alminni-mcp.git"},"description":"Alminni CLI - Configure AI-powered knowledge management for development teams","maintainers":[{"name":"jbiskur","email":"jbiskur@gmail.com"}],"readme":"# Alminni CLI\n\nA command-line tool to configure AI-powered knowledge management for development teams using Alminni MCP integration.\n\n## Overview\n\nThe Alminni CLI provides two essential commands for setting up Alminni MCP integration:\n\n- **`init`** - Initialize your project with Alminni configuration files and IDE integration\n- **`install`** - Configure MCP server connection to Alminni service\n\n### agents.md Support\n\nYou can opt into the emerging `AGENTS.md` standard to provide cross-IDE guidance to AI agents.\n\nGenerate a starter `AGENTS.md` during init with:\n\n```bash\nnpx @alminni/mcp-server init --agents\n```\n\nThis creates an `AGENTS.md` in your project root with a concise template aligned with this repo (TypeScript, Bun, MCP, Alminni). Prefer `AGENTS.md` for shared guidance and keep IDE-specific files minimal.\n\nThis CLI enables AI assistants in your IDE to access and create memory fragments, search team knowledge, explore relationships, and maintain institutional knowledge across your development team.\n\n## Installation\n\n```bash\nnpm install -g @alminni/mcp-server\n```\n\nOr use directly with npx:\n\n```bash\nnpx @alminni/mcp-server init\nnpx @alminni/mcp-server install\n```\n\n## Commands\n\n### Initialize Project\n\nInitialize your project with Alminni configuration:\n\n```bash\nnpx @alminni/mcp-server init\n```\n\nOptions:\n\n- `--ide <ide>` - IDE to configure (default: \"cursor\")\n- `--output-dir <dir>` - Output directory for IDE config files (default: \".\")\n- `--workspace-id <id>` - Optional: Alminni workspace ID to fetch fragment types\n- `--api-token <token>` - Optional: Alminni API access token to fetch fragment types\n- `--alminni-url <url>` - Optional: Alminni API URL (default: \"<https://alminni.com>\")\n- `--skip-auto-install` - Skip automatic MCP server installation (default: false)\n- `--pre-prompt <text>` - Custom pre-prompt to prepend to system prompt\n- `--agents` - Also generate an `AGENTS.md` file at project root (default: false)\n\n#### Pre-Prompt Customization\n\nThe `init` command supports customizing the AI system prompt for your specific project needs through pre-prompts:\n\n**Methods to specify a pre-prompt:**\n\n1. **CLI Option**: Use `--pre-prompt \"Your custom instructions\"` directly in the command\n2. **File-Based**: Create a `.pre-prompt.md` file in your project root directory  \n3. **Interactive**: The CLI will prompt you if no pre-prompt is provided via the above methods\n\n**Pre-prompt behavior:**\n- Pre-prompts are **prepended** to the system prompt fetched from Alminni API\n- They allow project-specific customization (coding standards, patterns, preferences)\n- The final prompt structure: `Custom Pre-Prompt` → `Alminni API System Prompt`\n\n**Example usage:**\n\n```bash\n# Via CLI option\nnpx @alminni/mcp-server init --pre-prompt \"Follow strict TypeScript patterns and use functional programming\"\n\n# Via file (create .pre-prompt.md in project root)\necho \"Use our company's coding standards and always include unit tests\" > .pre-prompt.md\nnpx @alminni/mcp-server init\n```\n\n**Use cases:**\n- Project-specific coding standards and patterns\n- Team conventions and best practices  \n- Technology-specific guidelines\n- Custom AI behavior preferences\n\n#### Auto-Detection & Auto-Install Behavior\n\nThe `init` command includes intelligent auto-detection and auto-install features:\n\n1. **IDE Detection**: Automatically detects existing MCP installations across multiple IDEs\n2. **Auto-Install**: If no MCP installation is found, prompts to automatically install\n3. **Smart Configuration**: Creates IDE-specific configuration files with repository context\n\n**Supported IDEs for Auto-Detection:**\n\n- **Cursor**: `~/.cursor/mcp.json`, `~/Library/Application Support/Cursor/`, `~/.config/cursor/`\n- **Claude Desktop**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n- **VS Code**: `~/Library/Application Support/Code/User/`, `~/.vscode/`\n- **Cline**: `~/.cline/`, `~/Library/Application Support/Cline/`, `~/.config/cline/`\n- **Zed**: `~/.zed/`, `~/Library/Application Support/Zed/`, `~/.config/zed/`\n- **Windsurf**: `~/.windsurf/`, `~/Library/Application Support/Windsurf/`, `~/.config/windsurf/`\n- **JetBrains IDEs**: `~/Library/Application Support/JetBrains/*/mcp.json`\n- **Sublime Text**: `~/Library/Application Support/Sublime Text/Packages/User/`\n- **Vim/Neovim**: `~/.vim/`, `~/.config/nvim/`\n- **Emacs**: `~/.emacs.d/`\n\nThis command creates project-specific IDE configuration files:\n\n- `.cursor/rules/alminni.mdc` - Cursor IDE rules for Alminni MCP integration\n\nThe configuration includes:\n\n- Repository context and workspace mapping\n- Fragment type definitions (knowledge, recipe, solution, template, code-snippet, styling)\n- Available Alminni MCP tools and usage guidelines\n- Pre-task and post-task workflows for AI assistants\n\n### Install MCP Server Connection\n\nConfigure MCP server connection to Alminni:\n\n```bash\nnpx @alminni/mcp-server install --api-token <token>\n```\n\nOptions:\n\n- `--api-token <token>` - Alminni API access token (required)\n- `--alminni-url <url>` - Alminni API URL (default: \"<https://alminni.com>\")\n- `--db-path <path>` - Custom database file path (default: \"~/.alminni-mcp/cache.db\")\n- `--local` - Configure local stdio MCP server (alias of `--force-legacy-mode`)\n- `--force-legacy-mode` - Force stdio mode instead of modern HTTP streaming\n\nThis command:\n\n1. Validates your Alminni API connection and authentication\n2. Configures the MCP server connection in your IDE's configuration\n3. Sets up the remote HTTP transport to Alminni MCP endpoint\n4. Creates the database directory structure for local caching\n\n### Run Local MCP Server (Legacy/Development)\n\nFor backwards compatibility or development purposes, run a local MCP server:\n\n```bash\nnpx @alminni/mcp-server server\n```\n\nOptions:\n\n- Environment variables:\n  - `ALMINNI_API_TOKEN` or `ALMINNI_ACCESS_TOKEN` - Your API token (required)\n  - `ALMINNI_BASE_URL` - Alminni API URL (default: \"https://alminni.com\")  \n  - `DEFAULT_WORKSPACE_ID` - Default workspace ID for operations\n\n**Note**: This local server mode is provided for backwards compatibility with older IDE configurations. The remote MCP server connection (configured via `install` command) is recommended for optimal performance and reliability.\n\n## Usage Workflow\n\n1. **Get your API token** from the Alminni web interface\n\n2. **Initialize your project** (with workspace selection):\n\n   ```bash\n   npx @alminni/mcp-server init --api-token <token>\n   ```\n\n   Or let the CLI prompt you for the token:\n\n   ```bash\n   npx @alminni/mcp-server init\n   ```\n\n   **With pre-prompt customization:**\n\n   ```bash\n   # With custom pre-prompt via CLI\n   npx @alminni/mcp-server init --api-token <token> --pre-prompt \"Follow our React coding standards\"\n   \n   # With pre-prompt file\n   echo \"Use TypeScript strict mode and functional patterns\" > .pre-prompt.md\n   npx @alminni/mcp-server init --api-token <token>\n   ```\n\n3. **Install MCP server connection**:\n\n   ```bash\n   npx @alminni/mcp-server install --api-token <token>\n   ```\n\n4. **Restart your IDE** to load the MCP server configuration\n\n## Alminni MCP Tools\n\nOnce configured, AI assistants in your IDE will have access to these Alminni tools:\n\n### **Core Fragment Management**\n\n- **`create_memory_fragment`** - Create new memory fragments (knowledge, recipe, solution, template, etc.)\n- **`search_memory_fragments`** - AI-powered semantic search with similarity scores and filters\n- **`get_memory_fragment_content`** - Retrieve full content of specific fragments by ID\n\n### **Knowledge Discovery & Navigation**\n\n- **`find_related_fragments`** - Discover fragments connected through shared tags and relationships\n- **`explore_workspace_graph`** - Get knowledge graph visualization with nodes and relationships\n- **`explore_tag_connections`** - Navigate fragments through specific tag relationships\n- **`list_workspaces`** - List accessible workspaces with permissions\n\n### **AI Assistant Workflow**\n\nThe tools are designed for a comprehensive knowledge management workflow:\n\n1. **Search existing knowledge** first (`search_memory_fragments`)\n2. **Explore relationships** if you need more context:\n   - `explore_workspace_graph` - Overall knowledge structure\n   - `explore_tag_connections` - Tag-based relationships\n   - `find_related_fragments` - Fragment connections\n3. **Create new fragments** when discovering novel solutions (`create_memory_fragment`)\n4. **Iterate** until you have complete context for your task\n\n## Configuration\n\n### Remote MCP Server Configuration (Recommended)\n\nThe CLI updates your IDE's MCP configuration file (e.g., `~/.cursor/mcp.json`) with:\n\n```json\n{\n  \"mcpServers\": {\n    \"alminni\": {\n      \"url\": \"https://alminni.com/api/mcp\",\n      \"transport\": \"http\",\n      \"headers\": {\n        \"Authorization\": \"Bearer your-api-token\"\n      }\n    }\n  }\n}\n```\n\n### Local MCP Server Configuration (Legacy)\n\nFor backwards compatibility with IDEs requiring stdio MCP servers:\n\n```json\n{\n  \"mcpServers\": {\n    \"alminni-local\": {\n      \"command\": \"npx\",\n      \"args\": [\"@alminni/mcp-server\", \"server\"],\n      \"env\": {\n        \"ALMINNI_API_TOKEN\": \"your-api-token\",\n        \"ALMINNI_BASE_URL\": \"https://alminni.com\"\n      }\n    }\n  }\n}\n```\n\n**Environment Variables for Local Server:**\n- `ALMINNI_API_TOKEN` or `ALMINNI_ACCESS_TOKEN` - Your API token (required)\n- `ALMINNI_BASE_URL` - Alminni API URL (default: \"https://alminni.com\")\n- `DEFAULT_WORKSPACE_ID` - Default workspace ID for operations\n\n### Project Configuration Files\n\nThe `init` command creates project-specific configuration:\n\n**`.cursor/rules/alminni.mdc`** - Contains:\n\n- Repository and workspace context mapping\n- Fragment type definitions and IDs\n- Complete Alminni MCP tool documentation\n- Usage guidelines and workflow instructions\n- Pre-task and post-task workflows for AI assistants\n- Custom pre-prompt content (if specified during init)\n\n### Database & Caching\n\nThe `install` command sets up local database structure:\n\n- **Default location**: `~/.alminni-mcp/cache.db`\n- **Purpose**: Local caching and sync state management\n- **Customizable**: Use `--db-path` to specify custom location\n\n## Package Architecture\n\nThis package provides **two modes** of Alminni MCP integration:\n\n### 🌐 Remote MCP Server (Recommended)\n\nThe primary and recommended integration method:\n\n- **What it is**: Direct HTTP connection from your IDE to Alminni MCP service\n- **Configuration**: Via `init` and `install` CLI commands  \n- **Benefits**: Always up-to-date, no local server management, optimal performance\n- **Integration Flow**: `IDE MCP Client` → `alminni.com/api/mcp`\n\n### 🖥️ Local MCP Server (Legacy/Backwards Compatibility)\n\nA local proxy server for older IDE configurations or special use cases:\n\n```bash\n# Run local MCP server mode\nnpx @alminni/mcp-server server\n\n# Or with specific configuration\nALMINNI_API_TOKEN=\"your-token\" npx @alminni/mcp-server server\n```\n\n**Local Server Features:**\n- **Proxy Mode**: Acts as a local MCP server that proxies requests to Alminni API\n- **Stdio Transport**: Compatible with IDEs that require stdio MCP servers\n- **Demo Mode**: Falls back to demo tools when Alminni API is unavailable\n- **Error Handling**: Structured JSON-RPC error responses with proper error codes\n\n**When to use Local Server:**\n- ⚠️ **Legacy IDE configurations** that require stdio MCP servers\n- 🔧 **Development and testing** of MCP integration\n- 🌐 **Network-restricted environments** requiring local proxy\n\n**Important Notes:**\n- 🚨 **Use Remote MCP Server when possible** - it's faster, more reliable, and always current\n- 📦 **Backwards Compatibility** - Local server mode is maintained for older IDE setups\n- 🔄 **Real-time Sync** - Local server includes background streaming for real-time updates\n\n### Integration Flow Comparison\n\n**Remote (Recommended):**\n1. **CLI Configuration** (`init` + `install`) →\n2. **IDE MCP Client** →\n3. **Alminni MCP Service** (hosted at alminni.com)\n\n**Local (Legacy):**\n1. **CLI Configuration** (`init` + `install`) →\n2. **Local MCP Server** (`npx @alminni/mcp-server server`) →\n3. **IDE MCP Client** (via stdio) →\n4. **Alminni MCP Service** (proxied)\n\n## Troubleshooting\n\n### Common Issues\n\n**\"API token is required\"** - The `init` command requires an API token to fetch workspace information and fragment types. Provide it via:\n\n- Command line: `--api-token <token>`\n- Environment variable: `ALMINNI_API_TOKEN`\n- Interactive prompt (CLI will ask if not provided)\n\n**\"Failed to connect to Alminni service\"** - Check:\n\n- Network connectivity to alminni.com\n- API token validity and permissions\n- Workspace access permissions\n\n**\"MCP server not found in IDE\"** - After installation:\n\n- Restart your IDE completely\n- Check MCP configuration file exists (e.g., `~/.cursor/mcp.json`)\n- Verify the configuration JSON syntax is valid\n\n**\"Pre-prompt not appearing in generated rules\"** - Check:\n\n- Pre-prompt was specified correctly via `--pre-prompt`, `.pre-prompt.md` file, or interactive prompt\n- API credentials are provided (pre-prompts require successful API connection)\n- Generated `.cursor/rules/alminni.mdc` file contains your custom pre-prompt at the top\n\n**\"Want to update pre-prompt for existing project\"** - Solutions:\n\n- Re-run `init` command with new `--pre-prompt` value (will prompt to overwrite existing files)\n- Manually edit the `.pre-prompt.md` file and re-run `init`\n- Update the generated `.cursor/rules/alminni.mdc` file directly (not recommended as it may be overwritten)\n\n## Requirements\n\n- Node.js >= 18.0.0\n- Valid Alminni workspace and API credentials\n- Compatible IDE with MCP support (Cursor, Claude Desktop, VS Code, etc.)\n\n## License\n\nMIT\n","readmeFilename":"README.md"}