@manfred-kunze-dev/backbone-mcp-server 2.6.0-dev.4 → 2.7.0-dev.2

package/README.md

@@ -1,66 +1,30 @@
 # Backbone MCP Server
 
-An [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server that exposes the Backbone AI platform as tools for LLMs. It lets AI assistants manage projects, define schemas, run extractions, convert documents, transcribe audio, and more — all through a standardized tool interface.
+An [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server that gives AI coding assistants direct access to the [Backbone AI](https://backbone.manfred-kunze.dev) platform — manage projects, run extractions, convert documents, and more from your IDE.
 
-## Setup
-
-### Prerequisites
-
-- **Node.js** >= 18.0.0
-- **Backbone backend** running and accessible (local or remote)
-- A valid **API key** for the Backbone backend
-
-### Install Dependencies
-
-```bash
-cd mcp
-npm install
-```
-
-### Build
-
-```bash
-npm run build
-```
-
-This compiles TypeScript from `src/` into `dist/`.
-
-### Environment Variables
-
-| Variable | Required | Default | Description |
-|---|---|---|---|
-| `BACKBONE_API_KEY` | Yes | — | API key for authenticating with the Backbone backend |
-| `BACKBONE_BASE_URL` | No | `https://backbone.manfred-kunze.dev/api` | Base URL of the Backbone backend including the API prefix. Override for local development (e.g. `http://localhost:8080/api`) |
-| `MCP_TRANSPORT` | No | `stdio` | Transport mode: `stdio` or `http` |
-| `MCP_HTTP_PORT` | No | `3100` | Port for the HTTP transport (only used when `MCP_TRANSPORT=http`) |
-
-### Running the Server
-
-**Stdio transport** (default — for use with Claude Code, Cursor, etc.):
+## Installation
 
 ```bash
-BACKBONE_API_KEY=your-key BACKBONE_BASE_URL=http://localhost:8080/api npm start
+npm install -g @manfred-kunze-dev/backbone-mcp-server
 ```
 
-**HTTP transport** (for network-accessible deployments):
+Or run directly with `npx` (no install needed):
 
 ```bash
-BACKBONE_API_KEY=your-key BACKBONE_BASE_URL=http://localhost:8080/api MCP_TRANSPORT=http npm start
+npx @manfred-kunze-dev/backbone-mcp-server
 ```
 
-The HTTP server exposes:
-- `POST /mcp` — MCP Streamable HTTP endpoint
-- `GET /health` — Health check
+## Quick Start
 
-**Development mode** (auto-recompile on changes):
+1. Create an API key in the Backbone dashboard under **API Keys**
+2. Add the server to your IDE's MCP configuration (see below)
+3. Start asking your AI assistant to manage your Backbone resources
 
-```bash
-npm run dev
-```
+## IDE Configuration
 
-### Connecting to Claude Code
+### Claude Code
 
-Add the server to your Claude Code MCP configuration (`.claude/settings.local.json` or similar):
+Add to `.claude/settings.local.json` in your project root:
 
 ```json
 {
@@ -69,18 +33,17 @@ Add the server to your Claude Code MCP configuration (`.claude/settings.local.js
       "command": "npx",
       "args": ["@manfred-kunze-dev/backbone-mcp-server"],
       "env": {
-        "BACKBONE_API_KEY": "your-api-key",
-        "BACKBONE_BASE_URL": "http://localhost:8080/api"
+        "BACKBONE_API_KEY": "sk_your_api_key"
       }
     }
   }
 }
 ```
 
-### Connecting to Cursor
+### Cursor
+
+Add to `.cursor/mcp.json` in your project root:
 
-Add to your `.cursor/mcp.json`:
-u
 ```json
 {
   "mcpServers": {
@@ -88,224 +51,74 @@ u
       "command": "npx",
       "args": ["@manfred-kunze-dev/backbone-mcp-server"],
       "env": {
-        "BACKBONE_API_KEY": "your-api-key",
-        "BACKBONE_BASE_URL": "http://localhost:8080/api"
+        "BACKBONE_API_KEY": "sk_your_api_key"
       }
     }
   }
 }
 ```
 
-> **Installing from the GitLab registry:** Configure npm to use the GitLab registry for the `@manfred-kunze-dev` scope by adding this to your `.npmrc`:
-> ```
-> @manfred-kunze-dev:registry=https://gitlab.com/api/v4/projects/<PROJECT_ID>/packages/npm/
-> //gitlab.com/api/v4/projects/<PROJECT_ID>/packages/npm/:_authToken=<YOUR_TOKEN>
-> ```
-
----
-
-## Available Tools
-
-### Projects
-
-Manage projects within your organization.
-
-| Tool | Description | Parameters |
-|---|---|---|
-| `backbone_list_projects` | List projects with optional search and pagination | `search?`, `page?`, `size?`, `sort?` |
-| `backbone_get_project` | Get a project by ID | `projectId` |
-| `backbone_create_project` | Create a new project | `name`, `description?` |
-| `backbone_update_project` | Update a project | `projectId`, `name?`, `description?` |
-| `backbone_delete_project` | Delete a project and all its data (irreversible) | `projectId` |
-
-### Schemas
-
-Define extraction schemas within projects. Schemas describe the structure of data to extract.
-
-| Tool | Description | Parameters |
-|---|---|---|
-| `backbone_list_schemas` | List schemas in a project | `projectId`, `search?`, `page?`, `size?`, `sort?` |
-| `backbone_get_schema` | Get a schema by ID | `projectId`, `schemaId` |
-| `backbone_create_schema` | Create a new schema | `projectId`, `name`, `description?`, `content?` |
-| `backbone_update_schema` | Update a schema | `projectId`, `schemaId`, `name?`, `description?`, `content?` |
-| `backbone_delete_schema` | Delete a schema and all its versions (irreversible) | `projectId`, `schemaId` |
-
-### Schema Versions
-
-Manage versioned snapshots of schema definitions.
-
-| Tool | Description | Parameters |
-|---|---|---|
-| `backbone_create_schema_version` | Create a new version (becomes active) | `projectId`, `schemaId`, `jsonSchema`, `changeDescription?` |
-| `backbone_list_schema_versions` | List all versions of a schema | `projectId`, `schemaId`, `page?`, `size?` |
-| `backbone_get_schema_version` | Get a specific version | `projectId`, `schemaId`, `versionId` |
-| `backbone_get_latest_schema_version` | Get the latest active version | `projectId`, `schemaId` |
-| `backbone_activate_schema_version` | Re-activate a historical version | `projectId`, `schemaId`, `versionId` |
-
-### Schema Testing
-
-Validate schemas and test extractions without persisting data.
-
-| Tool | Description | Parameters |
-|---|---|---|
-| `backbone_validate_schema` | Validate a JSON Schema definition | `projectId`, `schemaId`, `jsonSchema` |
-| `backbone_test_schema` | Test a schema against sample text with AI extraction | `projectId`, `schemaId`, `jsonSchema`, `sampleText`, `model` |
-
-### Extractions
-
-Extract structured data from text using schemas and AI models.
-
-| Tool | Description | Parameters |
-|---|---|---|
-| `backbone_create_extraction` | Extract data from text (sync or async) | `projectId`, `schemaId`, `inputText`, `model`, `schemaVersionId?`, `async?` |
-| `backbone_get_extraction` | Get an extraction by ID (check status or retrieve results) | `projectId`, `extractionId` |
-| `backbone_list_extractions` | List extractions with filtering | `projectId`, `status?`, `schemaVersionId?`, `search?`, `page?`, `size?`, `sort?` |
-| `backbone_estimate_tokens` | Estimate token usage without executing | `projectId`, `schemaId`, `inputText`, `schemaVersionId?` |
-| `backbone_rerun_extraction` | Re-run an existing extraction | `projectId`, `extractionId` |
-
-### Document Conversion
-
-Convert documents (PDF, DOCX, etc.) to Markdown, text, HTML, or JSON.
-
-| Tool | Description | Parameters |
-|---|---|---|
-| `backbone_convert_document` | Convert documents from URLs, base64, or local files | `sources[]` (type, url/data/path, filename), `outputFormats?`, `pageRange?`, `async?` |
-| `backbone_get_task_status` | Check status of an async conversion task | `taskId`, `wait?` |
-| `backbone_get_task_result` | Get the result of a completed conversion | `taskId` |
-
-Each source in `sources` can be:
-- **`url`** — fetch from a URL
-- **`base64`** — provide raw base64 data with a filename
-- **`file`** — provide a local file path (automatically read and encoded)
-
-### Audio Transcription
-
-Transcribe audio files using AI models.
-
-| Tool | Description | Parameters |
-|---|---|---|
-| `backbone_transcribe_audio` | Transcribe an audio file | `filePath`, `model`, `language?`, `prompt?`, `responseFormat?`, `temperature?` |
-
-Supported formats: flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav, webm.
-
-### AI Gateway
+### Windsurf
 
-Access multiple AI providers through a unified OpenAI-compatible interface.
+Add to `.windsurf/mcp.json` in your project root:
 
-| Tool | Description | Parameters |
-|---|---|---|
-| `backbone_chat` | Send a chat completion request | `model`, `messages[]`, `temperature?`, `max_tokens?`, `top_p?`, `frequency_penalty?`, `presence_penalty?`, `stop?`, `response_format?`, `tools?`, `tool_choice?` |
-| `backbone_list_models` | List available AI models and providers | *(none)* |
-
-Models use the format `provider/model` (e.g. `openai/gpt-4o`, `anthropic/claude-sonnet-4-5-20250929`).
-
-### API Documentation
-
-Browse the backend's OpenAPI documentation by section. Useful for understanding endpoint details, request/response shapes, and parameter constraints.
-
-| Tool | Description | Parameters |
-|---|---|---|
-| `backbone_list_api_doc_sections` | List available doc sections (tags) with endpoint counts | *(none)* |
-| `backbone_get_api_docs` | Fetch filtered docs for a specific section | `tag` |
-
-> **Note:** Requires `SPRINGDOC_ENABLED=true` on the backend. If docs are disabled, these tools return an informative error message.
-
-The `get_api_docs` tool returns only the endpoints and schemas relevant to the requested tag, keeping context usage minimal. The OpenAPI spec is cached in memory after the first fetch.
-
----
-
-## Development
-
-```bash
-# Build
-npm run build
-
-# Dev mode (watch + auto-recompile)
-npm run dev
-
-# Start
-npm start
-
-# Type-check without emitting
-npm run typecheck
-
-# Debug with MCP Inspector
-npm run inspect
+```json
+{
+  "mcpServers": {
+    "backbone": {
+      "command": "npx",
+      "args": ["@manfred-kunze-dev/backbone-mcp-server"],
+      "env": {
+        "BACKBONE_API_KEY": "sk_your_api_key"
+      }
+    }
+  }
+}
 ```
 
-### OpenAPI Type Generation
-
-Types are generated from the backend's OpenAPI spec using `openapi-typescript`. This ensures that all API calls are type-checked at compile time — if the backend renames a field, the MCP server won't compile until updated.
-
-**Prerequisites:**
-- A running Backbone backend at `http://localhost:8080` (or pass a custom URL as argument)
-- `BACKBONE_API_KEY` set — either in a `.env` file or as an environment variable
-
-```bash
-# Set up your .env (one-time)
-cp .env.example .env
-# Then edit .env with your API key
-
-# Full pipeline: fetch spec from backend + generate TypeScript types
-npm run generate
+### OpenAI Codex CLI
 
-# Individual steps:
-npm run generate:spec    # Fetch spec → openapi/openapi.json
-npm run generate:types   # Generate types → src/generated/openapi.d.ts
+Add to `~/.codex/config.json`:
 
-# CI drift check: compare committed spec against live backend
-npm run check:spec
+```json
+{
+  "mcpServers": {
+    "backbone": {
+      "command": "npx",
+      "args": ["@manfred-kunze-dev/backbone-mcp-server"],
+      "env": {
+        "BACKBONE_API_KEY": "sk_your_api_key"
+      }
+    }
+  }
+}
 ```
 
-> **Note:** `generate:types` does not need the API key — it reads from the committed `openapi/openapi.json` file. The `.env` file is loaded automatically by the `generate:spec` and `check:spec` scripts.
-
-**When to regenerate:**
-- After any backend API change (new endpoints, renamed fields, changed DTOs)
-- The `check:spec` script can be used in CI to detect stale types automatically
+Works with any MCP-compatible client using the same configuration pattern.
 
-**How it works:**
+## Environment Variables
 
-1. `generate:spec` — Fetches the OpenAPI spec from the backend's `/v3/api-docs` endpoint and saves it to `openapi/openapi.json`
-2. `generate:types` — Runs `openapi-typescript` to convert `openapi.json` into TypeScript type definitions at `src/generated/openapi.d.ts`
-3. `check:spec` — CI guard that compares the committed `openapi.json` against the live backend. Exits non-zero if they differ.
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `BACKBONE_API_KEY` | Yes | — | API key for authenticating with the Backbone backend |
+| `BACKBONE_BASE_URL` | No | `https://backbone.manfred-kunze.dev/api` | Base URL of your Backbone instance |
+| `MCP_TRANSPORT` | No | `stdio` | Transport mode: `stdio` or `http` |
+| `MCP_HTTP_PORT` | No | `3100` | Port for HTTP transport |
 
-Both `mcp/` and `cli/` share the same backend spec and generated types.
+## Available Tools
 
-### Project Structure
+| Category | Tools |
+|----------|-------|
+| **Projects** | List, get, create, update, delete projects |
+| **Schemas** | CRUD operations, version management, validation, testing |
+| **Extractions** | Create extractions (sync/async), estimate tokens, re-run |
+| **Document Conversion** | Convert PDFs, DOCX, images to Markdown/text/HTML/JSON |
+| **Transcription** | Transcribe audio files (flac, mp3, mp4, ogg, wav, webm) |
+| **AI Gateway** | Chat completions, list available models |
+| **API Docs** | Browse API documentation by section |
 
-```
-mcp/
-├── openapi/
-│   ├── openapi.json             # Committed OpenAPI spec (generated)
-│   └── scripts/
-│       ├── fetch-spec.ts        # Downloads spec from running backend
-│       └── check-drift.ts       # CI guard for spec drift detection
-├── src/
-│   ├── index.ts                 # Entry point, transport setup, tool registration
-│   ├── client.ts                # openapi-fetch client factory with error middleware
-│   ├── errors.ts                # Error types and MCP error formatting
-│   ├── mime.ts                  # MIME type detection for file uploads
-│   ├── schema-compat.ts         # OpenAI-compatible schema enforcement
-│   ├── generated/
-│   │   └── openapi.d.ts         # Auto-generated TypeScript types (do not edit)
-│   └── tools/
-│       ├── ai-gateway.ts        # Chat completions & model listing
-│       ├── conversion.ts        # Document conversion
-│       ├── docs.ts              # API documentation browsing
-│       ├── extraction.ts        # Data extraction
-│       ├── projects.ts          # Project CRUD
-│       ├── schema-testing.ts    # Schema validation & testing
-│       ├── schema-versions.ts   # Schema version management
-│       ├── schemas.ts           # Schema CRUD
-│       └── transcription.ts     # Audio transcription
-├── dist/                        # Compiled output (generated)
-├── package.json
-└── tsconfig.json
-```
+For full tool documentation, see the [Backbone docs](https://backbone.manfred-kunze.dev).
 
-### Adding New Tools
+## License
 
-1. Create a new file in `src/tools/` following the existing pattern
-2. Export a `register(server: McpServer, client: ApiClient): void` function
-3. Import and call `register()` in `src/index.ts`
-4. Rebuild with `npm run build`
+Proprietary — see [LICENSE](./LICENSE) for details.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@manfred-kunze-dev/backbone-mcp-server",
-  "version": "2.6.0-dev.4",
+  "version": "2.7.0-dev.2",
   "description": "MCP server for the Backbone AI platform",
   "type": "module",
   "main": "dist/index.js",
@@ -36,11 +36,7 @@
     "registry": "https://registry.npmjs.org",
     "access": "public"
   },
-  "repository": {
-    "type": "git",
-    "url": "https://gitlab.com/manfred-kunze-dev/backbone.git",
-    "directory": "mcp"
-  },
+  "homepage": "https://backbone.manfred-kunze.dev",
   "files": [
     "dist/**/*.js",
     "dist/**/*.d.ts"