{
  "markdown": "# Slima MCP\n\n[![npm version](https://badge.fury.io/js/slima-mcp.svg)](https://www.npmjs.com/package/slima-mcp)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\nMCP (Model Context Protocol) Server for [Slima](https://slima.ai) - AI Writing IDE for Novel Authors.\n\nConnect your Slima books to **any MCP-compatible AI tool** - one server, all platforms.\n\n## Supported Platforms\n\n### Desktop Applications (Local MCP - stdio)\n\n| Platform | Status | Notes |\n|----------|--------|-------|\n| Claude Desktop | ✅ | Native MCP support |\n| ChatGPT Desktop | ✅ | Developer Mode (2025.10+) |\n| Gemini CLI | ✅ | Native MCP support |\n| Cursor | ✅ | Native MCP support |\n| VS Code | ✅ | Via MCP extensions |\n\n### Web Applications (Remote MCP - HTTP)\n\n| Platform | Status | Notes |\n|----------|--------|-------|\n| Claude.ai | ✅ | OAuth login, no token needed |\n| ChatGPT Web | ✅ | OAuth login, no token needed |\n\n> MCP became the industry standard in December 2025 when Anthropic, OpenAI, and Block co-founded the Agentic AI Foundation under the Linux Foundation.\n\n## Features\n\n### Book Management\n- **Create** new books\n- List and view your books\n- Get file/folder structure\n- Track writing statistics\n\n### File Operations\n- **Read** any file by path\n- **Edit** specific text (search & replace)\n- **Write** (replace) file content\n- **Create** new files\n- **Delete** files\n- **Append** content to files\n- **Search** across all files\n\n### AI Beta Reader\n- Get feedback from virtual reader personas\n- Analyze chapters with different reader perspectives\n\n## Quick Start\n\n**Pick the path that matches how you use AI:**\n\n- ⭐ Use **claude.ai / ChatGPT in a web browser** → [Recommended: web connector](#recommended-claudeai--chatgpt-web-auto-updating) *(one-time setup, auto-updates forever)*\n- Use **Claude Desktop / Cursor / Gemini CLI locally** → [Local install with `npx`](#local-claude-desktop--cursor--gemini-cli)\n- Running in air-gapped / enterprise environments → [Self-host](#self-host-advanced)\n\n### Recommended: claude.ai / ChatGPT Web (auto-updating)\n\nIf you chat with Claude or ChatGPT in a browser, this is the easiest and most future-proof option. **Configure once and you will automatically get every Slima MCP update** — no upgrade commands, no config edits.\n\n**MCP URL:** `https://mcp.slima.ai/mcp`\n\n#### claude.ai (Pro / Max / Team / Enterprise)\n\n1. Sign in at [claude.ai](https://claude.ai).\n2. Open **Settings → Connectors** (or **Integrations** depending on your plan).\n3. Click **Add custom connector**.\n4. Fill in:\n   - **Name:** `Slima`\n   - **URL:** `https://mcp.slima.ai/mcp`\n5. Click **Connect** → you will be redirected to slima.ai to approve → return to claude.ai.\n6. The Slima tools icon appears in your chat input. You're done.\n\n#### ChatGPT (Plus / Pro, Developer Mode)\n\n1. Sign in at [chatgpt.com](https://chatgpt.com).\n2. Open **Settings → Connectors → Advanced** and toggle **Developer Mode** on (2025.10+).\n3. Back in **Connectors**, click **Create → Custom MCP Server**.\n4. Fill in:\n   - **Name:** `Slima`\n   - **Server URL:** `https://mcp.slima.ai/mcp`\n   - **Authentication:** OAuth\n5. Click **Create** → approve the OAuth flow.\n\nAfter setup, Slima features roll out automatically on your next conversation. No restarts, no reinstalls.\n\n---\n\n### Local: Claude Desktop / Cursor / Gemini CLI\n\nUse this if you want offline-friendly operation, faster startup, or you need to run MCP alongside other stdio servers.\n\n**Recommended config** — pinned to the major version so you pick up new features automatically but never break on a `1.0` release:\n\n#### Claude Desktop\n\nEdit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\\Claude\\claude_desktop_config.json` (Windows):\n\n```json\n{\n  \"mcpServers\": {\n    \"slima\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"slima-mcp@0\"],\n      \"env\": {\n        \"SLIMA_API_TOKEN\": \"slima_your_token_here\"\n      }\n    }\n  }\n}\n```\n\nGet your token from [Slima Settings](https://app.slima.ai/settings/api-tokens) or run `npx slima-mcp@0 auth` once to save it to disk.\n\n#### Cursor\n\n```json\n{\n  \"mcpServers\": {\n    \"slima\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"slima-mcp@0\"],\n      \"env\": {\n        \"SLIMA_API_TOKEN\": \"slima_your_token_here\"\n      }\n    }\n  }\n}\n```\n\n#### Gemini CLI\n\n```bash\ngemini mcp add slima --command \"npx -y slima-mcp@0\"\n```\n\n> **Why `slima-mcp@0` instead of `slima-mcp` / `slima-mcp@latest`?** Using `@0` pins to the current major version — npx still fetches new `0.x.y` releases automatically (so you get features + bug fixes), but when we ship `1.0.0` with breaking changes you won't silently pick it up without updating your config. We'll announce the `@1` switch in the release notes.\n\n#### Migrating from a global install\n\nIf you already installed globally with `npm install -g slima-mcp`:\n\n```bash\n# Remove the old global install (optional but cleaner)\nnpm uninstall -g slima-mcp\n\n# Change your config `command` from \"slima-mcp\" to the npx form above, and restart the client.\n```\n\nOr, if you want to stay on a global install, remember to periodically run:\n\n```bash\nnpm install -g slima-mcp@latest\n```\n\nOtherwise your local client will drift from the MCP tools/schema the Slima backend exposes.\n\n### Self-host (advanced)\n\nYou can also clone this repo and deploy the Cloudflare Worker yourself. See `wrangler.toml` + `npm run deploy:worker`. Not required for normal use.\n\n---\n\n## Remote MCP Security\n\nThe hosted Remote MCP Server at `https://mcp.slima.ai/mcp` uses:\n\n- **OAuth 2.0 + PKCE** for authentication — no tokens copy-pasted.\n- **No secrets stored server-side** — credentials never leave Slima's auth server.\n- **Session-based**: OAuth tokens are stored in Cloudflare KV, scoped per session.\n- **Revocable anytime** from [Slima Settings](https://app.slima.ai/settings/api-tokens).\n\n---\n\n## Book Types: Writing Studio vs Script Studio\n\nSlima books come in two flavors, distinguished by the `book_type` field. MCP behaves slightly differently for each:\n\n| | 📖 Writing Studio (`book_type: \"book\"`) | 📝 Script Studio (`book_type: \"script\"`) |\n|---|---|---|\n| **Creation via MCP** | ✅ `create_book` works | ❌ use the Slima app UI |\n| **Read** (any file) | ✅ | ✅ |\n| **Write / Edit / Delete** | ✅ any path | ✅ only under `.script_studio/planning/**/*` |\n| Structured files (`series.json`, `*.character`, `*.scene`, `*.storyline`, `*.note`, `*.location`, `season.json`, `episode.json`) | n/a | ❌ read-only via MCP — edits must go through the Script Studio UI |\n| `analyze_chapter` (AI Beta Reader) | ✅ | ❌ not yet supported on structured scenes |\n| `search_content` | all files | structured files excluded by default; pass `include_structured: true` to include them |\n\nFor per-book details, ask your AI client to read the resource `slima://books/{book_token}/schema` — it returns a JSON spec of exactly which paths are writable/read-only for that specific book.\n\n`list_books` tags every book with its studio icon (📝 / 📖) so you (and the AI) can tell them apart at a glance.\n\n---\n\n## Available Tools\n\n### Book Management\n\n| Tool | Description |\n|------|-------------|\n| `create_book` | Create a new book in your library |\n| `list_books` | List all books in your Slima library |\n| `get_book` | Get details of a specific book |\n| `get_book_structure` | Get the file/folder structure of a book |\n| `get_writing_stats` | Get writing statistics for a book |\n\n### File Operations\n\n| Tool | Description |\n|------|-------------|\n| `read_file` | Read content of any file by path |\n| `edit_file` | Edit specific text using search & replace |\n| `write_file` | Replace entire content of a file |\n| `create_file` | Create a new file in a book |\n| `delete_file` | Delete a file from a book |\n| `append_to_file` | Append content to end of a file |\n| `search_content` | Search for text across all files |\n\n### AI Beta Reader\n\n| Tool | Description |\n|------|-------------|\n| `list_personas` | List available beta reader personas |\n| `analyze_chapter` | Get AI beta reader feedback on a chapter |\n\n## Usage Examples\n\nOnce configured, you can ask your AI:\n\n**Book & Content:**\n- \"Create a new book called 'My Novel'\"\n- \"List my books in Slima\"\n- \"Show me the structure of my novel\"\n- \"Read chapter 3 of my book\"\n- \"What are my writing stats?\"\n\n**File Operations:**\n- \"Read the character profile for my protagonist\"\n- \"Edit chapter 1 and change 'John' to 'James'\"\n- \"Create a new file called worldbuilding.md with notes about the magic system\"\n- \"Search for all mentions of 'blue eyes' in my book\"\n- \"Append this new paragraph to chapter 5\"\n\n**AI Feedback:**\n- \"Get feedback on chapter 5 from a young reader perspective\"\n- \"Analyze my opening scene from a critic's perspective\"\n\n## CLI Commands\n\n```bash\nslima-mcp auth      # Authenticate with browser (recommended)\nslima-mcp status    # Check authentication status\nslima-mcp logout    # Remove saved credentials\nslima-mcp --help    # Show help\nslima-mcp --version # Show version\n```\n\nToken is stored in `~/.slima/credentials.json` with secure permissions.\n\n## Environment Variables\n\n| Variable | Required | Default | Description |\n|----------|----------|---------|-------------|\n| `SLIMA_API_TOKEN` | No* | - | Your Slima API token |\n| `SLIMA_API_URL` | No | `https://api.slima.ai` | API endpoint (for development) |\n| `DEBUG` | No | `false` | Enable debug logging |\n\n*Not required if you used `slima-mcp auth`\n\n## Development\n\n### Local CLI Development\n\n```bash\n# Clone the repository\ngit clone https://github.com/slima-ai/slima-mcp.git\ncd slima-mcp\n\n# Install dependencies\nnpm install\n\n# Build CLI\nnpm run build\n\n# Run tests\nnpm test\n\n# Run in development mode\nnpm run dev\n```\n\n### Cloudflare Worker Development\n\n```bash\n# Build the Worker\nnpm run build:worker\n\n# Run Worker locally\nnpm run dev:worker\n\n# Deploy to Cloudflare\nnpm run deploy:worker\n\n# Deploy to preview environment\nnpm run deploy:worker:preview\n```\n\n### Project Structure\n\n```\nslima-mcp/\n├── src/\n│   ├── core/           # Shared core modules\n│   │   ├── api/        # Slima API Client\n│   │   ├── tools/      # MCP Tool implementations\n│   │   └── utils/      # Utilities and errors\n│   ├── cli/            # CLI entry point (stdio transport)\n│   │   ├── index.ts    # CLI main\n│   │   ├── auth.ts     # Authentication commands\n│   │   └── server.ts   # MCP Server for CLI\n│   └── worker/         # Cloudflare Worker (HTTP transport)\n│       ├── index.ts    # Worker entry point\n│       └── oauth.ts    # OAuth 2.0 + PKCE client\n├── wrangler.toml       # Cloudflare Worker config\n├── tsup.config.ts      # CLI build config\n└── tsup.worker.config.ts # Worker build config\n```\n\n## Security\n\n- API tokens are stored locally and never shared\n- All communication with Slima API uses HTTPS\n- Tokens can be revoked anytime from Slima settings\n\n## Release & Deployment\n\n### npm (Automatic)\n\nMerge to `main` with a version bump in `package.json` triggers automatic npm publish via GitHub Actions.\n\n```bash\n# 1. Bump version on dev branch\nnpm version patch   # 0.1.10 → 0.1.11\n\n# 2. Merge to main\ngit checkout main && git merge dev && git push\n\n# 3. CI runs tests → publish.yml publishes to npm + creates git tag\n```\n\n### Cloudflare Worker (Manual)\n\nWorker deployment is separate from npm. Deploy after code changes:\n\n```bash\nnpm run deploy:worker           # Production (mcp.slima.ai)\nnpm run deploy:worker:preview   # Staging\n```\n\n### MCP Registry (Manual)\n\nTo publish/update the server listing on the [MCP Registry](https://registry.modelcontextprotocol.io/):\n\n```bash\nmcp-publisher login github\nmcp-publisher publish\n```\n\nRequires `mcpName` in `package.json` and `server.json` in repo root.\n\n## Operational Notes\n\n### Debugging Worker OAuth\n\nWhen troubleshooting claude.ai or ChatGPT connector issues:\n\n```bash\n# Live logs from production Worker\nwrangler tail slima-mcp\n```\n\nAll OAuth endpoints log key parameters (client_id, redirect_uri, token prefix, etc.) to help trace the flow.\n\n### Worker OAuth Flow (claude.ai / ChatGPT)\n\n```\nClient POST /mcp → 401 + WWW-Authenticate header\n  → Client GET /.well-known/oauth-protected-resource\n  → Client GET /.well-known/oauth-authorization-server\n  → Client POST /register (DCR)\n  → Client redirects user to GET /authorize\n    → Worker redirects to Rails OAuth\n    → User authorizes → Rails redirects to Worker /callback\n    → Worker issues auth code → redirects to client callback\n  → Client POST /token (exchange code for access_token)\n  → Client POST /mcp (Authorization: Bearer {access_token})\n```\n\n### Known Constraints\n\n- Worker Bearer token validation accepts all non-empty tokens (not just `slima_` prefix) to support OAuth-issued tokens. Rails API performs actual validation.\n- `getTokenFromSession()` checks Authorization header first, then falls back to cookie session.\n- MCP Inspector (`npx @modelcontextprotocol/inspector`) is useful for testing the full OAuth flow independently.\n\n## License\n\nMIT\n\n## Links\n\n- [Slima Website](https://slima.ai)\n- [Slima App](https://app.slima.ai)\n- [MCP Documentation](https://modelcontextprotocol.io)\n- [MCP Registry](https://registry.modelcontextprotocol.io/)\n- [Report Issues](https://github.com/slima-ai/slima-mcp/issues)\n",
  "bytes": 13194,
  "sha": "4d7b05ebd6cea637d400936498c31da9fd7cdb568ff4f2a9a3e4bb33af8405d7",
  "repo_slug": "slima-ai/slima-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_slima_ai_slima_936beecc/readme"
}