ocp-mcp-server 0.2.0b1__tar.gz

ocp_mcp_server-0.2.0b1/.claude/settings.local.json

@@ -0,0 +1,44 @@
+{
+  "permissions": {
+    "allow": [
+      "WebFetch(domain:api-dev.bimplus.net)",
+      "Bash(curl -s -I \"https://api-dev.bimplus.net/swagger/index.html\")",
+      "Bash(curl -s \"https://api-dev.bimplus.net/swagger/index.html\")",
+      "Bash(curl *)",
+      "Bash(python3 *)",
+      "Bash(.venv/bin/pip install *)",
+      "Bash(pip3 --version)",
+      "Read(//usr/local/bin/**)",
+      "Read(//opt/homebrew/bin/**)",
+      "Bash(brew list *)",
+      "Bash(command -v pyenv)",
+      "Bash(pyenv versions *)",
+      "Bash(command -v uv)",
+      "Bash(uv python *)",
+      "Read(//Users/jabualdenien/.pyenv/**)",
+      "Bash(uv venv *)",
+      "Bash(uv pip *)",
+      "Bash(.venv/bin/python3 *)",
+      "Bash(.venv/bin/python *)",
+      "Bash(pkill -x \"Claude\")",
+      "Bash(open -a \"Claude\")",
+      "Bash(grep -v '^$')",
+      "Bash(/Users/jabualdenien/Downloads/claude-test/bimplus-api-mcp/.venv/bin/pip install *)",
+      "Bash(uv --version)",
+      "Bash(gtimeout 5 .venv/bin/python server.py)",
+      "Bash(/Users/jabualdenien/Downloads/claude-test/bimplus-api-mcp/.venv/bin/python *)",
+      "Read(//Users/jabualdenien/Downloads/claude-test/**)",
+      "Bash(zip -r bimplus-api-mcp.zip bimplus-api-mcp/ --exclude 'bimplus-api-mcp/.venv/*' --exclude 'bimplus-api-mcp/__pycache__/*' --exclude bimplus-api-mcp/runtime_config.json --exclude bimplus-api-mcp/CLAUDE.md)",
+      "Bash(zip -r bimplus-api-mcp.zip bimplus-api-mcp/ --exclude 'bimplus-api-mcp/.venv/*' --exclude 'bimplus-api-mcp/__pycache__/*' --exclude bimplus-api-mcp/runtime_config.json --exclude bimplus-api-mcp/CLAUDE.md --exclude 'bimplus-api-mcp/.claude/*')",
+      "Bash(unzip -l bimplus-api-mcp.zip)",
+      "Bash(rm bimplus-api-mcp.zip)",
+      "Bash(zip bimplus-api-mcp.zip bimplus-api-mcp/server.py bimplus-api-mcp/swagger.json bimplus-api-mcp/pyproject.toml bimplus-api-mcp/install.sh bimplus-api-mcp/README.md)",
+      "Bash(chmod +x bimplus-api-mcp/install.sh)",
+      "Bash(bash -n /Users/jabualdenien/Downloads/claude-test/bimplus-api-mcp/install.sh)",
+      "Bash(open *)",
+      "Bash(ls /Users/jabualdenien/Downloads/GIT/ocp-mcp-server/bimplus-api-mcp/*.md /Users/jabualdenien/Downloads/GIT/ocp-mcp-server/bimplus-api-mcp/../*.md 2>/dev/null)",
+      "Read(//Users/jabualdenien/Downloads/GIT/ocp-mcp-server/**)",
+      "Bash(uv build *)"
+    ]
+  }
+}

ocp_mcp_server-0.2.0b1/.gitignore

@@ -0,0 +1,35 @@
+# Runtime configuration with credentials - NEVER commit
+runtime_config.json
+
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+.eggs/
+dist/
+build/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log
+
+# Environment files with secrets
+.env
+.env.local
+.env.*.local

ocp_mcp_server-0.2.0b1/CLAUDE.md

@@ -0,0 +1,83 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What this project is
+
+A Python MCP (Model Context Protocol) server that dynamically exposes the BimPlus API (394 endpoints) as MCP tools, plus a handful of hand-crafted "smart tools" that chain multiple API calls.
+
+## Running and development
+
+```bash
+# Run the MCP server directly (stdio transport)
+.venv/bin/python server.py
+
+# Install/sync dependencies (uses uv or pip into the local .venv)
+uv pip install -e .
+# or
+.venv/bin/pip install -e .
+```
+
+There are no tests and no build step — the single source file is `server.py`.
+
+## Architecture
+
+All logic lives in `server.py`. The startup flow is:
+
+1. `swagger.json` is loaded at module import time into `SPEC`.
+2. `_populate_tools()` iterates every path+method in the spec and registers an entry in `_TOOLS` (a `dict[name → (method, path, op)]`). Tool names are derived from the HTTP method and path slug, deduplicated with a numeric suffix.
+3. The MCP `list_tools` handler returns the hand-crafted config/search tools followed by all auto-generated API tools.
+4. The MCP `call_tool` handler dispatches to config tools first, then looks up the name in `_TOOLS` and executes the request via `httpx`.
+
+### Config system
+
+Runtime config is layered (later wins):
+- Defaults (`_DEFAULT_CONFIG`)
+- Environment variables (`BIMPLUS_TOKEN`, `BIMPLUS_BASE_URL`, `BIMPLUS_TEAM_SLUG`, etc.)
+- `runtime_config.json` (written by the `set_bimplus_config` tool)
+
+Config is read fresh on every tool call so changes take effect without a restart.
+
+### Hand-crafted tools
+
+Beyond the auto-generated API tools, `server.py` defines these named tools:
+
+| Tool | Purpose |
+|---|---|
+| `ocp_help` | Front-door routing; returns capabilities and example prompts |
+| `set_bimplus_config` | Write fields to `~/.config/ocp-mcp/runtime_config.json` |
+| `get_bimplus_config` | Read current config (sensitive fields masked) |
+| `authenticate_bimplus` | POST `/v2/authorize` with stored credentials and save token |
+| `start_sso_login` | Full OAuth2 PKCE browser flow: asyncio local server → Keycloak → cross-token → Identity token |
+| `set_bimplus_sso_token` | Validate and save a pasted Bearer/Identity token |
+| `list_my_teams` | GET `/v2/teams` with normalized output |
+| `list_team_projects` | GET projects for a team with optional filter |
+| `list_project_models` | GET divisions (models) for a project with optional filter |
+| `search_objects` | 5-step chain: topology → divisions → filter → exportobjects → filtered results |
+| `count_elements_by_type` | Count objects per element type (parallel requests) |
+| `count_elements_by_property_value` | Count objects of a type where a property matches a value |
+| `bulk_update_property_by_filter` | Safe mass attribute update with dry-run, batching, and read-back verification |
+| `project_dashboard_insights` | One-call project dashboard: issues, element totals, top types, area/volume |
+
+### Auto-generated tool naming
+
+`_build_tool_name(method, path)` strips the `/v2` prefix, converts `{param}` to `by_param`, replaces non-alphanumeric characters with underscores, and prefixes with the HTTP method. Names are truncated to 61 chars to leave room for dedup suffixes.
+
+### Schema resolution
+
+`_resolve_schema()` walks `$ref` chains up to depth 4, flattening OpenAPI component schemas into inline MCP-compatible JSON Schema. Request bodies are exposed as a single `body` property.
+
+### `teamSlug` auto-fill
+
+If a tool has a `teamSlug` path parameter and the caller omits it, the value from config is substituted automatically before the request is made.
+
+## Key files
+
+- `server.py` — entire server (~2700 lines)
+- `swagger.json` — BimPlus OpenAPI v2 spec (394 paths, ~2.3 MB)
+- `~/.config/ocp-mcp/runtime_config.json` — persisted runtime config (token, base_url, team_slug, credentials)
+- `pyproject.toml` — project metadata, entry point `ocp-mcp = "server:main"`
+
+## Credentials note
+
+`runtime_config.json` contains live credentials and tokens. Do not commit it. The file is read at runtime and written by `set_bimplus_config`.

ocp_mcp_server-0.2.0b1/PKG-INFO

@@ -0,0 +1,384 @@
+Metadata-Version: 2.4
+Name: ocp-mcp-server
+Version: 0.2.0b1
+Summary: OCP (Open Collaboration Platform) MCP server — exposes the BimPlus API as Claude tools [BETA]
+License: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: mcp>=1.0.0
+Description-Content-Type: text/markdown
+
+# BimPlus API — Claude MCP Server
+
+Gives Claude desktop direct access to the full BimPlus API (394 endpoints) plus smart tools for searching and managing BIM objects.
+
+---
+
+## Prerequisites
+
+| Requirement | Notes |
+|---|---|
+| **macOS** | Windows not yet supported |
+| **Python 3.10+** | Check with `python3 --version`. Download from [python.org](https://www.python.org/downloads/) if needed |
+| **Claude desktop** | Download from [claude.ai/download](https://claude.ai/download) |
+| **BimPlus account** | You need your Nemetschek email and password |
+
+---
+
+## Security Notes
+
+**⚠️ Credentials in `runtime_config.json`**
+
+When you authenticate, your token is saved to `~/.config/ocp-mcp/runtime_config.json`. **This file contains live credentials and should NEVER be committed to version control.**
+
+**Guidelines:**
+- ✅ `.gitignore` already contains `runtime_config.json` — verify this before committing
+- ✅ Restrict file permissions: `chmod 600 runtime_config.json` (owner read-only)
+- ✅ Never share this file or its contents with others
+- ✅ Tokens automatically expire; re-authenticate when needed
+- ⚠️ For production deployments, use secure credential storage (e.g., AWS Secrets Manager, HashiCorp Vault)
+
+**SSL Verification (Advanced)**
+By default, SSL certificate verification is **enabled** (`verify_ssl=true`). For staging environments with self-signed certificates, you can disable it via environment variable:
+```bash
+export BIMPLUS_VERIFY_SSL=false
+```
+Or in `runtime_config.json`:
+```json
+{
+  "verify_ssl": "false"
+}
+```
+⚠️ Only disable for development/staging — always enable for production.
+
+---
+
+## Installation (2 minutes)
+
+**1. Download and extract** the zip file to a permanent location on your Mac.  
+   > Tip: put it somewhere it won't be accidentally deleted, e.g. `~/Applications/bimplus-mcp/`
+
+**2. Open Terminal** — press `Cmd+Space`, type `Terminal`, press Enter.
+
+**3. Run the installer:**
+
+```bash
+cd /path/to/bimplus-api-mcp
+bash install.sh
+```
+
+Replace `/path/to/bimplus-api-mcp` with the actual folder you extracted to.  
+Example: `cd ~/Applications/bimplus-mcp && bash install.sh`
+
+**4. Restart Claude desktop** — quit (`Cmd+Q`) and reopen it.
+
+**5. Authenticate** — in a new Claude conversation, type:
+
+```
+Use authenticate_bimplus to log me in with email jabualdenien@nemetschek.com
+```
+
+Claude will ask for your password and save the token for future sessions.
+
+---
+
+## What you can do after setup
+
+Just ask Claude in plain English:
+
+- *"Show me all models in team acme-corp"*
+- *"Find all doors on the second floor"*
+- *"What are the properties of element XYZ?"*
+- *"Search for walls with fire rating EI60"*
+
+---
+
+## Smart tools (LLM-friendly)
+
+This server exposes all API endpoints from `swagger.json` and also provides higher-level tools that combine multiple API calls.
+
+### `ocp_help`
+- Purpose: Front-door routing tool. Returns available capabilities and example prompts.
+- Use when: Prompt contains "OCP", "BimPlus", "construction platform", or when unsure which tool to use.
+- Trigger phrases: "what can OCP do", "help with OCP", "what tools are available", "open OCP".
+- Output: Full list of capabilities with example prompts.
+
+### `set_bimplus_config`
+- Purpose: Save runtime connection settings (token, base URL, team, credentials).
+- Use when: Authentication or API calls fail due to missing config.
+- Output: Saved config with sensitive fields masked.
+
+### `get_bimplus_config`
+- Purpose: Read current runtime settings.
+- Use when: You want to verify what token/team/base URL is active.
+- Output: Current config with sensitive fields masked. Shows a first-run hint if no config file exists yet.
+
+### `authenticate_bimplus`
+- Purpose: Log in with stored credentials and save a fresh token.
+- Primary tool for: "login to OCP", "log in to OCP", "authenticate OCP", "connect to BimPlus".
+- Required config first: `user_id`, `password`, `application_id`.
+- Output: Auth status and token metadata.
+
+### `start_sso_login`
+- Purpose: Full browser-based SSO login — opens the Allplan login page and captures the token automatically via OAuth2 PKCE. No manual token copy-paste required.
+- Use when: "Login to OCP with SSO", "browser login", "login via portal".
+- Flow: browser opens → user logs in → token saved automatically.
+- Optional input: `clear_password` (default `true`), `timeout_seconds` (default `120`).
+- Output: Login status and masked token metadata.
+
+### `set_bimplus_sso_token`
+- Purpose: Manually paste a Bearer token (fallback when browser login isn't possible).
+- Use when: You already have an OCP/BimPlus access token from another source.
+- Required input: `token`.
+- Optional input: `token_type` (default `Bearer`), `clear_password` (default `true`).
+- Output: Token validation status and masked token metadata.
+
+### `list_my_teams`
+- Purpose: List teams available to the current user.
+- Use when: You ask "list my teams" / "show available teams" / "search team".
+- Optional input: `query`, `limit`.
+- Output: Normalized team rows (`id`, `name`, `slug`).
+
+### `list_team_projects`
+- Purpose: List projects in a team and optionally search by name/ID.
+- Use when: You ask "list all projects" / "search team project".
+- Optional input: `team_slug`, `query`, `limit`.
+- Output: Normalized project rows (`id`, `name`, `number`, `status`).
+
+### `list_project_models`
+- Purpose: List models (project divisions) in the current project and optionally filter them.
+- Use when: You ask "show the model names" / "which models are available here" / "list models" / "what models are in this project".
+- Optional input: `team_slug`, `project_id`, `query`, `limit`.
+- Output: Normalized model rows (`id`, `name`) plus the current model when available.
+
+### `search_objects`
+- Purpose: Run object search across project topology with optional filters.
+- Required input: `project_id`.
+- Filter options:
+   - `conditions`: structured equality filters.
+   - `filter_string`: raw advanced BIMPlus filter syntax.
+- Output: Filtered result hierarchy/export payload.
+
+### `count_elements_by_type`
+- Purpose: Count objects per element type in a project.
+- Required input: `project_id`.
+- Optional input: `team_slug`, `include_zero`, `max_concurrency`.
+- Output: Per-type counts, per-discipline totals, and errors.
+
+### `count_elements_by_property_value`
+- Purpose: Count objects where a property equals a value for a specific type.
+- Required input: `project_id`, `type_name_or_id`, `property_name`, `property_value`.
+- Optional input: `case_sensitive`, `trim_whitespace`, `sample_limit`.
+- Output: Matched count, sample IDs, and top value distribution.
+
+### `bulk_update_property_by_filter`
+- Purpose: Safely update an attribute for all objects matched by a filter.
+- Required input: `project_id`, `type_name_or_id`, `filter_property_name`, `filter_property_value`, `attribute_id`, `new_value`.
+- Safety flow:
+   - Preview first with `dry_run=true`.
+   - Apply only with `dry_run=false` and `confirm=true`.
+   - Optionally verify read-back with `verify=true` and `target_property_name`.
+- Output: Match summary, update status, failed IDs, verification details.
+
+### `project_dashboard_insights`
+- Purpose: Build a one-call project dashboard with project details, issue summaries, element totals, top types, and area/volume insights.
+- Required input: `project_id`.
+- Optional input: `team_slug`, `top_n_types`, `sample_issue_limit`, `include_element_samples`, `area_property_names`, `volume_property_names`.
+- Output: Normalized dashboard JSON suitable for charts/tables and follow-up analysis.
+
+### Generic API endpoint tools
+- Purpose: Direct access to each endpoint in the BIMPlus OpenAPI spec.
+- Naming: Derived from HTTP method and path, for example `get_by_teamslug_projects_by_projectid_element_types`.
+- Output: HTTP status and raw endpoint response.
+
+---
+
+## Example prompts
+
+**Getting started**
+- "What can OCP do?" *(routes to ocp_help)*
+- "Login to OCP." *(credentials in config)*
+- "Login to OCP with SSO." *(browser opens automatically)*
+- "Login to OCP with SSO token <paste token>." *(manual paste fallback)*
+
+**Discovery**
+- "List my teams."
+- "List all projects in my current team."
+- "Which models are available here?"
+- "Show OCP projects in team <slug>."
+
+**Analysis**
+- "Count all object types in project <project_id>."
+- "How many Columns have material C30/37?"
+- "Show project dashboard for <project_id>."
+- "Search OCP objects where material is C30/37."
+
+**Edits**
+- "Preview updating Product name to Claude for Columns where material is C30/37."
+- "Apply that update now with confirm=true and verify using target property Product name."
+
+**Low-level**
+- "Call get_by_teamslug_projects_by_projectid_element_types for team <team_slug> and project <project_id>."
+
+---
+
+## Tool Catalog Modes And Fallback
+
+This server supports three catalog modes:
+
+- `smart`: smart tools only (lowest token usage)
+- `hybrid`: smart tools + curated autogenerated endpoints
+- `full`: smart tools + full autogenerated endpoint catalog (can be capped)
+
+To reduce "tool not available" responses while staying efficient, smart mode can expose a fallback slice:
+
+- `tool_catalog_fallback_mode`: `off` | `hybrid` | `full`
+- `tool_catalog_fallback_limit`: number of fallback autogenerated tools to expose in smart mode
+
+You can set these via `set_bimplus_config`:
+
+```text
+Set tool_catalog_mode to "smart"
+Set tool_catalog_fallback_mode to "hybrid"
+Set tool_catalog_fallback_limit to 25
+```
+
+Or directly in `runtime_config.json` / env vars (`BIMPLUS_TOOL_CATALOG_*`).
+
+---
+
+## Session1 Regression Script
+
+You can run a full scenario regression matching the historical `session1.md` workflow.
+
+### Safe mode (default, no writes)
+
+```bash
+.venv/bin/python scripts/session1_regression.py
+```
+
+This runs authentication, read-only checks, the new model discovery step, and the bulk-update **dry-run** safety step.
+If stored credentials are stale, the auth step falls back to validating the existing session token so the rest of the regression can still complete.
+
+### Full parity mode (includes write apply)
+
+```bash
+.venv/bin/python scripts/session1_regression.py --apply-writes
+```
+
+This also executes the bulk update apply step and writes data (same target value used in session: `Claude`).
+
+### Useful flags
+
+```bash
+.venv/bin/python scripts/session1_regression.py \
+   --team-slug ctf-nemetschek-allplan-gmbh-ft \
+   --project-id 3e9fed73-0c06-48fb-888a-d5b2ad7b3c05 \
+   --model-id 9deba3db-2c4a-4ce6-b1ec-45c5b2b35929 \
+   --keep-config
+```
+
+Notes:
+- Exit code is `0` when all scenarios pass, otherwise `1`.
+- By default, the script restores your previous runtime config after execution.
+
+---
+
+## Changing your team or project
+
+```
+Set the BimPlus team slug to "my-team-name"
+Set the BimPlus project ID to "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
+```
+
+Claude will remember these settings between sessions.
+
+---
+
+## Troubleshooting
+
+**"bimplus-api" does not appear in Claude's tools**
+- Make sure you fully quit and reopened Claude desktop after installation.
+- Re-run `bash install.sh` to check for errors.
+
+**Authentication fails**
+- Ask Claude: *"What is the current BimPlus config?"* to verify the token field.
+- Try authenticating again: *"Run authenticate_bimplus"*
+- If you see HTTP 401 Unauthorized, update `password` and/or `application_id` via `set_bimplus_config`, then retry.
+- Do not store masked values (e.g. `Micr...09`) in `runtime_config.json`; authentication requires the full plaintext password.
+
+### Prefer SSO Login (No Password In Config)
+
+The easiest way — no password, no copy-paste:
+
+```text
+Login to OCP with SSO.
+```
+
+Claude opens the Allplan login page in your browser. Once you complete login, the token is captured and saved automatically. The whole flow takes about 15 seconds.
+
+**How it works under the hood:**
+1. A temporary local HTTP server starts on port `8766`.
+2. Your browser opens to the Allplan Keycloak login page (OAuth2 PKCE flow).
+3. After login, Keycloak redirects to `http://localhost:8766/callback` with an authorization code.
+4. The server exchanges the code for a Keycloak token, then exchanges that for a BimPlus Identity token via `/v2/cross-token` → `/v2/cross-authorize`.
+5. The Identity token is saved to config; the local server shuts down.
+
+**Fallback — paste a token manually:**
+
+If the browser flow isn't available, call `set_bimplus_sso_token` and paste a token directly:
+
+```text
+Use set_bimplus_sso_token with:
+- token: <PASTE_ACCESS_TOKEN>
+- token_type: Identity
+- clear_password: true
+```
+
+The server validates via `GET /v2/authorize` before saving.
+
+**Config knobs:**
+- `sso_callback_port` — local port for the OAuth redirect (default `8766`)
+- `sso_auth_server` — Keycloak base URL (auto-derived from `base_url` if empty)
+
+**Python not found**
+- Install Python 3.10+ from [python.org](https://www.python.org/downloads/) and re-run `install.sh`.
+
+---
+
+## What install.sh does
+
+1. Checks that Python 3.10+ is installed
+2. Creates a local `.venv` virtual environment (uses `uv` if available, otherwise `python -m venv`)
+3. Installs the two dependencies: `mcp` and `httpx`
+4. Patches `~/Library/Application Support/Claude/claude_desktop_config.json` to register the `bimplus-api` MCP server entry pointing at the local venv and `server.py`
+
+It is safe to re-run — it will update an existing installation in place.
+
+---
+
+## Sharing with colleagues
+
+Send them the zip and this message:
+
+> Extract the zip somewhere permanent (e.g. `~/Applications/bimplus-mcp/`), open Terminal, run `bash install.sh`, restart Claude desktop, then ask Claude to run `authenticate_bimplus` with your Nemetschek credentials.
+
+---
+
+## Files in this package
+
+| File | Purpose |
+|---|---|
+| `server.py` | The MCP server (all logic lives here) |
+| `swagger.json` | Full BimPlus API specification |
+| `pyproject.toml` | Python package metadata |
+| `install.sh` | Automated setup script |
+| `README.md` | This file |
+
+`runtime_config.json` is created automatically the first time you authenticate — it stores your token locally and is never sent anywhere except to the BimPlus API.