Skip to main content
Glama

MCPIdhall — FastMCP Server for the IDhall REST API

🇬🇧 English | 🇫🇷 Version française (README.fr.md)

License Python FastMCP OpenAPI Docker Build & Publish Docker

MCPIdhall is an open-source Model Context Protocol (MCP) server built with FastMCP, providing full read/write access to the IDhall REST API v1 (Humanperf Software — innovation management, continuous improvement, and action plan platform).


Key Features

  • Per-User JWT Authentication (Strict RBAC): Every user supplies their own IDhall JWT token; no shared credentials are stored on the server. All actions strictly respect each user's IDhall access profile.

  • 100% Coverage of All 208 IDhall v1 Endpoints: 33 curated, strongly-typed tools (initiatives, drafts, workflow transitions, action plans, contributions, memos, tags, opportunity analysis, users, 23 reference catalogs) + a universal idhall_api_request escape-hatch tool backed by a zero-latency local endpoint catalog.

  • Dual Transport: stdio (local desktop clients: Antigravity, Claude Desktop, Cursor, VS Code) and streamable-http / sse (shared multi-user team server).

  • Resilient & Hardened: Automatic exponential backoff on HTTP 429 / 5xx, structured RFC 7807 application/problem+json error formatting, non-root read_only multi-arch (amd64/arm64) Docker image published to GHCR.

  • Complete Bilingual Documentation (EN / FR): Embedded OpenAPI 3.1.0 specification (128 paths, 125 schemas), complete 208-endpoint synthesis, step-by-step user guide, and beginner-friendly Docker / Portainer / Nginx Proxy Manager guide.


Related MCP server: Advanced MCP Platform

Quick Start

1. Local Mode (stdio — Antigravity, Claude Desktop, Cursor, VS Code)

git clone https://github.com/smilebob/MCPIdhall.git
cd MCPIdhall
uv sync

Add the server to your MCP client configuration with your personal IDhall JWT token (My Account > Login & Security > REST API authentication tokens):

{
  "mcpServers": {
    "idhall": {
      "command": "uv",
      "args": ["--directory", "/path/to/MCPIdhall", "run", "mcp-idhall"],
      "env": {
        "IDHALL_API_TOKEN": "<your_idhall_jwt_token>"
      }
    }
  }
}

2. Multi-User Team Server (Docker / Portainer / streamable-http)

docker run -d \
  --name mcp-idhall \
  --restart unless-stopped \
  -p 127.0.0.1:8000:8000 \
  -e IDHALL_ALLOWED_HOSTS="*" \
  -e IDHALL_LANGUAGE="en" \
  -e IDHALL_TIMEZONE="UTC" \
  ghcr.io/smilebob/mcpidhall:latest

Each remote MCP client connects over HTTPS with its own user JWT:

{
  "mcpServers": {
    "idhall": {
      "url": "https://mcp-idhall.your-domain.com/mcp",
      "headers": {
        "Authorization": "Bearer <your_idhall_jwt_token>"
      }
    }
  }
}

(Your IDhall instance URL is automatically inferred from the JWT iss claim, or can be overridden via IDHALL_BASE_URL / X-IDhall-Base-Url.)


Exposed MCP Tools (33 Tools — 100% of 208 Endpoints)

Category

Tools

Identity & Discovery (4)

idhall_about, idhall_whoami, idhall_search_endpoints, idhall_get_endpoint_spec

Initiatives CRUD & Drafts (9)

idhall_list_ideas, idhall_count_ideas, idhall_get_idea, idhall_get_idea_input_availability, idhall_create_idea, idhall_create_idea_draft, idhall_publish_idea_draft, idhall_update_idea, idhall_delete_idea

Workflow & Stages (2)

idhall_get_idea_stage, idhall_transition_idea_stage (10 transitions + cancel)

Implementation & Action Plans (7)

idhall_get_idea_implementation, idhall_update_idea_implementation_progress, idhall_list_action_plan_tasks, idhall_create_action_plan_task, idhall_update_action_plan_task, idhall_update_task_progress, idhall_delete_action_plan_task

Collaboration & Opportunity (7)

idhall_list_idea_contributions, idhall_add_idea_contribution, idhall_get_idea_memo, idhall_set_idea_memo, idhall_get_idea_tags, idhall_manage_idea_tags, idhall_get_opportunity_analysis

Users & Reference Data (3)

idhall_list_users, idhall_get_user, idhall_list_reference_items (23 catalogs: plans, sites, organizations, categories, risks, stakeholders…)

Universal Escape Hatch (1)

idhall_api_request (full GET/POST/PUT/PATCH/DELETE access to all 208 endpoints)


Documentation & Resources

Document

🇬🇧 English

🇫🇷 Français

Project Overview

README.md

README.fr.md

User Guide (Beginner to Pro)

docs/USER_GUIDE.md

docs/GUIDE_UTILISATEUR.md

Docker, Portainer & NPM Guide

docs/DOCKER_PORTAINER_GUIDE.md

docs/GUIDE_DOCKER_PORTAINER.md

OpenAPI 3.1.0 Spec (208 endpoints)

docs/openapi.json

docs/openapi.json

API Synthesis (208 endpoints)

docs/IDHALL_API_SYNTHESE.md

docs/IDHALL_API_SYNTHESE.md

Running Tests

uv sync --extra dev
uv run pytest -v

License

Licensed under the Apache License 2.0 — see LICENSE. This is a community open-source project and is not affiliated with Humanperf Software.

Available Tools

33 tools
idhall_aboutIdhall AboutA

Retourne les informations sur la version d'IDhall et de son API REST.

Inputs: no named parameters. Returns: object

idhall_add_idea_contributionIdhall Add Idea ContributionC

Ajoute une contribution (commentaire) à une initiative.

Inputs: text (required), idea_id (required), sentiment. Returns: object

idhall_api_requestIdhall Api RequestA

Exécute un appel arbitraire vers n'importe lequel des 208 endpoints de l'API REST IDhall v1.

Avant d'utiliser cet outil sur un endpoint spécialisé (ex: audits, parties prenantes/contacts, ressources/pièces jointes, critères d'opportunité, lots de plan d'action), consultez son schéma avec idhall_search_endpoints et idhall_get_endpoint_spec.

Inputs: path (required), method (required), json_body, query_params.

idhall_count_ideasIdhall Count IdeasB

Compte le nombre d'initiatives correspondant au filtre donné (IdeaFilter).

Inputs: filter. Returns: object

idhall_create_action_plan_taskIdhall Create Action Plan TaskC

Ajoute une tâche au plan d'action d'une initiative (POST /api/v1/ideas/{id}/action-plan/tasks).

Inputs: title (required), idea_id (required), owner, phase, +3 more. Returns: object

idhall_create_ideaIdhall Create IdeaA

Crée et publie immédiatement une nouvelle initiative dans IDhall (POST /api/v1/ideas).

Inputs: plan (required), title (required), context, description, +1 more. Returns: object

idhall_create_idea_draftIdhall Create Idea DraftC

Crée une initiative à l'état brouillon (POST /api/v1/ideas/draft).

Inputs: title (required), plan, description, extra_fields. Returns: object

idhall_delete_action_plan_taskIdhall Delete Action Plan TaskC

Supprime une tâche d'un plan d'action (DELETE /api/v1/ideas/{id}/action-plan/tasks/{task_id}).

Inputs: idea_id (required), task_id (required). Returns: object

idhall_delete_ideaIdhall Delete IdeaB

Supprime définitivement une initiative (DELETE /api/v1/ideas/{id}).

Inputs: idea_id (required). Returns: object

idhall_get_endpoint_specIdhall Get Endpoint SpecA

Retourne le schéma complet (paramètres, payload, classes, réponse) d'un endpoint IDhall.

Lit d'abord le catalogue local ; interroge /api/v1/reference/endpoints/{endpoint_id} si absent. Exemple d'endpoint_id : GET__ideas, POST__ideas, PATCH__ideas__(id).

Inputs: endpoint_id (required). Returns: object

idhall_get_ideaIdhall Get IdeaA

Récupère les détails d'une initiative par son ID. Passez props pour obtenir plus que {id, title}.

Inputs: idea_id (required), props. Returns: object

idhall_get_idea_implementationIdhall Get Idea ImplementationC

Récupère les informations de mise en œuvre d'une initiative.

Inputs: idea_id (required), props. Returns: object

idhall_get_idea_input_availabilityIdhall Get Idea Input AvailabilityA

Retourne les propriétés disponibles/requises pour créer (idea_id=None) ou modifier une initiative.

Inputs: idea_id, plan_id. Returns: object

idhall_get_idea_memoIdhall Get Idea MemoC

Récupère le mémo d'une initiative.

Inputs: idea_id (required). Returns: object

idhall_get_idea_stageIdhall Get Idea StageB

Retourne l'étape de traitement en cours d'une initiative (GET /api/v1/ideas/{id}/stages/current).

Inputs: idea_id (required), props. Returns: object

idhall_get_idea_tagsIdhall Get Idea TagsC

Récupère les tags associés à une initiative.

Inputs: idea_id (required). Returns: object

idhall_get_opportunity_analysisIdhall Get Opportunity AnalysisC

Récupère l'analyse d'opportunité d'une initiative.

Inputs: idea_id (required), props. Returns: object

idhall_get_userIdhall Get UserB

Récupère la fiche d'un utilisateur IDhall par son ID.

Inputs: user_id (required), props. Returns: object

idhall_list_action_plan_tasksIdhall List Action Plan TasksC

Liste les tâches du plan d'action d'une initiative.

Inputs: idea_id (required), props. Returns: object

idhall_list_idea_contributionsIdhall List Idea ContributionsC

Liste les contributions d'une initiative.

Inputs: idea_id (required), props. Returns: object

idhall_list_ideasIdhall List IdeasB

Liste les initiatives IDhall avec pagination, projection (props) et filtres (filter).

Inputs: count, props, filter, offset, +1 more. Returns: object

idhall_list_reference_itemsIdhall List Reference ItemsC

Liste les éléments d'un référentiel IDhall (plans, sites, organizations, categories, risks, stakeholders, etc.).

Inputs: resource (required), count, props, filter, +2 more. Returns: object

idhall_list_usersIdhall List UsersC

Liste les utilisateurs IDhall avec pagination, projection (props) et filtres (UserFilter).

Inputs: count, props, filter, offset, +1 more. Returns: object

idhall_manage_idea_tagsIdhall Manage Idea TagsC

Ajoute (add), remplace (replace) ou supprime (remove) des tags sur une initiative.

Inputs: tags (required), idea_id (required), operation (required). Returns: object

idhall_publish_idea_draftIdhall Publish Idea DraftB

Publie une initiative brouillon existante (POST /api/v1/ideas/{id}/publish).

Inputs: idea_id (required), payload. Returns: object

idhall_search_endpointsIdhall Search EndpointsA

Recherche dans le catalogue local des 208 endpoints IDhall v1 (zéro appel réseau).

Utilisez cet outil pour trouver l'endpoint exact et son endpoint_id avant d'inspecter son schéma avec idhall_get_endpoint_spec ou d'appeler idhall_api_request.

Inputs: limit, query, method. Returns: result

idhall_set_idea_memoIdhall Set Idea MemoB

Définit ou remplace le mémo d'une initiative (PUT /api/v1/ideas/{id}/memo).

Inputs: memo (required), idea_id (required). Returns: object

idhall_transition_idea_stageIdhall Transition Idea StageB

Fait avancer ou annule l'étape de traitement d'une initiative.

Actions supportées :

  • standby, change-approver, request-details, request-expertise

  • approve--request-implementation-schedule, approve--launch-implementation, approve--end-implementation

  • reject, end-implementation, close

  • cancel (annule la dernière étape via DELETE /api/v1/ideas/{id}/stages/current)

Inputs: action (required), idea_id (required), payload. Returns: object

idhall_update_action_plan_taskIdhall Update Action Plan TaskC

Modifie une tâche d'un plan d'action (PATCH /api/v1/ideas/{id}/action-plan/tasks/{task_id}).

Inputs: fields (required), idea_id (required), task_id (required). Returns: object

idhall_update_ideaIdhall Update IdeaA

Modifie partiellement une initiative existante (PATCH /api/v1/ideas/{id}).

Ne passez dans fields que les propriétés à modifier.

Inputs: fields (required), idea_id (required). Returns: object

idhall_update_idea_implementation_progressIdhall Update Idea Implementation ProgressC

Met à jour l'état d'avancement de la mise en œuvre d'une initiative.

Inputs: idea_id (required), comment, percent, confidence. Returns: object

idhall_update_task_progressIdhall Update Task ProgressC

Met à jour l'avancement d'une tâche d'un plan d'action.

Inputs: idea_id (required), task_id (required), comment, percent, +1 more. Returns: object

idhall_whoamiIdhall WhoamiB

Identifie l'utilisateur associé au jeton JWT courant et récupère sa fiche IDhall.

Inputs: props. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    C2.9/5.0

    Scored across 33 tools

    Disambiguation4/5

    Most tools target a distinct resource+action (idea CRUD, draft lifecycle, stages, action-plan tasks, contributions, memo, tags, users, reference items), and the descriptions clarify the tricky pairs like create_idea vs create_idea_draft and update_action_plan_task vs update_task_progress. The main ambiguity is idhall_api_request, a catch-all that can do anything every other tool can, but the descriptions steer agents to the specialized tools first and to api_request only as fallback.

    Naming Consistency4/5

    Almost all tools use the predictable `idhall_` prefix plus verb_noun in snake_case (list_ideas, get_idea, create_action_plan_task, delete_action_plan_task). Minor deviations are idhall_about and idhall_whoami (no verb_noun) and idhall_manage_idea_tags, which uses a generic verb where add/remove/replace would be more explicit.

    Tool Count3/5

    33 tools is heavy for a single server, exceeding the comfortable 3-15 band, though it mirrors a large (208-endpoint) API and groups those endpoints into coherent domain tools rather than one-tool-per-endpoint. The presence of search_endpoints/get_endpoint_spec/api_request as a metatool layer partly justifies the breadth, but the surface still feels large for an agent to navigate.

    Completeness3/5

    Core idea lifecycle is well covered (create/draft/publish/update/delete, stages, implementation, tasks CRUD, memo, tags, contributions), so no major dead ends for the main workflow. However, several named sub-domains—audits, stakeholders/contacts, attachments/resources, opportunity criteria, plan lots—are reachable only through the raw api_request, and contributions have add/list but no edit or delete.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      C
      maintenance
      Enables authenticated clients to discover and call tools for scoped file listing/searching, request client-side LLM sampling, and receive real-time progress/log notifications over stdio or secure Streamable HTTP, with tenant/user workspace isolation and a loopback browser dashboard.
      7
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to search notes and manage tickets through tools that enforce per-agent JWT identity, least-privilege scopes, and deny-by-default policy, with every allowed or denied call written to a tamper-evident, redacted audit log. Runs over stdio for local clients or streamable HTTP with bearer auth for shared deployments.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI clients such as Claude Desktop/Web, Cursor, Windsurf, VS Code Copilot, and ChatGPT Actions to connect through a remote Streamable HTTP endpoint or stdio bridge to 12 deterministic tool suites covering claim/citation verification, Qur'anic and hadith research, clinical/proteomic/quantum/scientific analysis, security auditing, classical heritage search, catalog discovery, and billing activation.
      MIT