Architectural Overview

The Kibela MCP Service Gateway currently operates exclusively as a local process utilizing Standard Input/Output (STDIO) communication, ensuring compatibility with any conforming MCP client, including Claude Desktop or Visual Studio Code.

Tool exposure is restricted to those publicly documented GraphQL endpoints within Kibela that are deemed appropriate for MCP integration.

Primary Use Cases

• Information retrieval and querying within the Kibela repository.
• Orchestration of folder hierarchies and article organization within Kibela.
• Utilization of automated intelligence to augment content generation within the Kibela environment.

Prerequisites

1. The Docker runtime environment must be installed.
2. The Docker daemon must be active and operational.
3. A valid Kibela access token must be provisioned.
4. An application implementing the MCP client specification must be operational.

Deployment Instructions

Example: Configuration for Claude Desktop

Integrate the following configuration structure into your designated configuration file (claude_desktop_config.json). Environment variables specifying the Kibela base URL and the authentication token are essential.

{ "mcpServers": { "kibela": { "command": "docker", "args": [ "run", "-i", "-e", "KIBELA_ORIGIN", "-e", "KIBELA_ACCESS_TOKEN", "ghcr.io/kibela/kibela-mcp-server" ], "env": { "KIBELA_ORIGIN": "https://your-subdomain.kibe.la", "KIBELA_ACCESS_TOKEN": "***" } } } }

Direct Execution (Non-Docker Scenario)

If avoiding Docker, configure the gateway by specifying the absolute path to the executable script as the primary execution command. Ensure paths are fully qualified.

{ "mcpServers": { "kibela": { "command": "/path/to/kibela-mcp-server/bin/cli.mjs", "env": { "KIBELA_ORIGIN": "https://your-subdomain.kibe.la", "KIBELA_ACCESS_TOKEN": "***" } } } }

Exposed Toolset

Article Management Functions

• search_kibela_note - Execute a retrieval operation against Kibela articles.

• query: The core string for the search predicate (Mandatory).

• resources: Filter targeting specific resource types (Optional).
• coediting: Boolean indicator for co-author status (Optional).
• updated: Time constraint defining the modification window (Optional).
• groupIds: Filter based on associated Group Identifiers (Optional).
• folderIds: Filter based on containing Folder Identifiers (Optional).
• likerIds: Filter by User IDs who have liked the content (Optional).
• isArchived: Boolean flag to include/exclude archived items (Optional).

• sortBy: Parameter defining the criterion for result ordering (Optional).

• get_kibela_note_by_relay_id - Retrieve a specific article using its globally unique Relay Identifier.

• id: The Relay ID of the target article (Mandatory).

• get_kibela_note_from_path_or_url - Fetch an article based on its navigable web path or URL.

• path: The hierarchical path or full URL pointing to the article (Mandatory).

• get_kibela_notes - Retrieve a collection of articles housed within a specified directory structure.

• folderId: The identifier for the parent folder (Mandatory).

• first: Limit for fetching records starting from the beginning (Optional).

• last: Limit for fetching records starting from the end (Optional).

• create_kibela_note - Provision a new article entry.

• title: The designated title for the new entry (Mandatory).

• content: The main body text/data for the entry (Mandatory).
• draft: Boolean indicating if the article should be saved as a draft (Optional).
• groupIds: An array of Group IDs under which the article should reside (Mandatory).

• folders: Metadata specifying folder association (Optional).

  • groupId: Associated Group ID.
  • folderName: Name of the destination folder.

• update_kibela_note_content - Modify the substance of an existing article.

• id: The unique identifier of the article to be modified (Mandatory).
• newContent: The updated material to be written (Mandatory).
• baseContent: The content state prior to this modification attempt (Mandatory).

Directory Management Functions

• search_kibela_folder - Execute a search against the directory structure.

• query: Keyword used to filter directory names (Mandatory).

• get_kibela_folder_by_relay_id - Fetch a directory entity via its Relay ID.

• id: The Folder's Relay ID (Mandatory).

• first: Pagination limit for content enumeration within the folder (Optional).

• get_kibela_folder_from_path_or_url - Resolve a directory using its URL or hierarchical path string.

• path: The Folder's access path or URL (Mandatory).

• first: Pagination limit for content enumeration within the folder (Optional).

• get_kibela_folders - List available directories.

• first: Pagination limit for fetching leading entries (Optional).

• last: Pagination limit for fetching trailing entries (Optional).

• create_kibela_folder - Establish a novel directory structure.

• groupId: The Group Identifier where the folder is to be created (Mandatory).

• fullName: The complete, absolute path name defining the new directory's location (Mandatory).

• move_kibela_note_to_another_folder - Reassign an article's location.

• id: Identifier of the article being relocated (Mandatory).

• fromFolder: Origin folder context (Mandatory).
  • groupId: Source Group ID.
  • folderName: Source Folder Name.

• toFolder: Destination folder context (Mandatory).

  • groupId: Target Group ID.
  • folderName: Target Folder Name.

• attach_kibela_note_to_folder - Link an existing article to an additional directory without relocating it.

• id: Note ID (Mandatory).
• folder: Destination folder context metadata (Mandatory).
  • groupId: Group ID.
  • folderName: Folder name.

Annotation Interaction Functions

• create_kibela_comment - Post a new textual annotation to an article.

• content: The textual payload of the annotation (Mandatory).

• noteId: The Relay ID of the target article (Mandatory).

• create_kibela_comment_reply - Generate a response directed at an existing annotation.

• content: The reply's textual payload (Mandatory).
• commentId: The Relay ID of the parent annotation (Mandatory).

Auxiliary Retrieval Functions

• get_kibela_groups - Retrieve a list of accessible organizational groups.

• first: Pagination limit for leading results (Optional).

• last: Pagination limit for trailing results (Optional).

• get_kibela_feed_sections - Fetch structured data for specific feed views.

• kind: Identifier specifying the feed category (Mandatory).
• groupId: Identifier of the organizational group context (Mandatory).

Predefined Invocation Schemas

Content Review Schema

Accepts a direct URL and initiates a review process on the pointed-to Kibela resource.

Input definition:

typescript { url: string; // Must conform to standard URL format }

Information Search Schema

Takes a query string to locate pertinent data.

Input definition:

typescript { query: string; }

Contextual Article Retrieval Schema

Utilizes a URL to explore articles contextually related to the specified resource.

Input definition:

typescript { url: string; // Must conform to standard URL format }

Annotation Reflection Schema

Uses a URL to extract and process associated comments back into the note context.

Input definition:

typescript { url: string; // Must conform to standard URL format }

Configurability

Modification of the tool descriptions or invocation prompts is supported by generating a JSON configuration file that adheres to the following structure. Refer to server.ts for the definitive mapping of tool and prompt keys.

{ "tools": { "search_kibela_note": { "description": "New description" } }, "prompts": { "review": { "prompt": "New review prompt" } } }

This configuration file can then be made accessible to the running container via volume mounting, exemplified below:

{ "mcpServers": { "kibela": { "command": "docker", "args": [ "run", "-i", "-e", "KIBELA_ORIGIN", "-e", "KIBELA_ACCESS_TOKEN", "-v", "/path/to/kibela-mcp-server-config.json:/usr/src/app/kibela-mcp-server-config.json", "ghcr.io/kibela/kibela-mcp-server" ], "env": { "KIBELA_ORIGIN": "https://your-subdomain.kibe.la", "KIBELA_ACCESS_TOKEN": "***" } } } }

Development Workflow

Execution of required dependencies setup within the development container:

bash docker compose run mcp pnpm install

To initiate the service:

bash docker compose up

Validation using MCP Inspector

Testing connectivity and functionality via the dedicated inspection utility:

bash npx @modelcontextprotocol/inspector \ -e KIBELA_ORIGIN=https://your-subdomain.kibe.la \ -e KIBELA_ACCESS_TOKEN=*** \ docker compose exec mcp bin/cli.mjs

Software License

This software package is governed under the stipulations of the MIT License.

Historical Context: XMLHttpRequest (XHR)

XMLHttpRequest (XHR) denotes a specific programmatic interface realized as a JavaScript object. Its methods are designed to dispatch HTTP request transactions from a web browser environment toward a remote web server. The functionality provided allows applications running within the browser context to dispatch requests to the server subsequent to the initial page rendering, and subsequently receive data in return. XHR constitutes a core architectural component of Ajax programming paradigms. Prior to the widespread adoption of Ajax, the standard mechanisms for server interaction—namely, hyperlinking and form submission—typically necessitated a full page refresh upon completion.

== Historical Development == The conceptual foundation underpinning XMLHttpRequest was initially formulated in the year 2000 by the engineering teams at Microsoft Outlook. This concept was subsequently materialized within the Internet Explorer 5 browser release (1999). Critically, the initial implementation syntax did not employ the canonical XMLHttpRequest identifier. Instead, developers relied upon instantiating objects via ActiveXObject("Msxml2.XMLHTTP") or ActiveXObject("Microsoft.XMLHTTP"). As of Internet Explorer 7 (released in 2006), universal browser support for the standardized XMLHttpRequest identifier was achieved. The XMLHttpRequest identifier has since matured into the accepted standard across all dominant browser engines, including Mozilla’s Gecko rendering engine (since 2002), Safari 1.2 (since 2004), and Opera 8.0 (since 2005).

=== Standardization Trajectory === The World Wide Web Consortium (W3C) formally published the initial Working Draft specification for the XMLHttpRequest object on April 5, 2006. On February 25, 2008, the W3C advanced this to the Level 2 specification Working Draft. Key additions in Level 2 encompassed methods for tracking event progress, enabling requests across distinct domains (cross-site requests), and facilitating the handling of raw byte streams. By the conclusion of 2011, the features defined in the Level 2 draft were integrated back into the primary specification. In late 2012, the maintenance and evolution of the specification were officially transferred to the WHATWG group, which now sustains a continuously updated living document utilizing Web IDL notations.

== Operational Usage == Generally, executing a network request using XMLHttpRequest mandates the execution of several discrete programming steps:

1. Instantiation of an XMLHttpRequest object via its constructor function is required.
2. The open method must be invoked to delineate the transaction type, designate the target resource endpoint, and elect between synchronous or asynchronous execution modes.
3. For asynchronous operations, a callback listener must be established to receive notifications when the request's internal state transitions occur.
4. The transaction is initiated by calling the send method, optionally supplying data for transmission.
5. The state changes must be monitored within the established event listener. Upon successful receipt of response data from the server, it is typically accessible via the responseText property once the object reaches state 4 (the "done" state). Beyond these fundamental steps, XMLHttpRequest provides extensive configuration parameters to govern request transmission protocols and response processing methodologies. Custom header fields can be appended to modify server expectations. Data can be uploaded by passing payloads directly to the send call. Furthermore, the received response can be transparently parsed from JSON format into native JavaScript objects or streamed for processing incrementally instead of waiting for the complete payload. Finally, the operation can be terminated prematurely or configured with a timeout threshold.

== Inter-Domain Transactions (Cross-Domain Requests) ==

During the nascent stages of the World Wide Web's development, architects identified potential security vulnerabilities stemming from the ability to brea