Dixa Platform Interface (Gateway MCP)

An implementation of the Model Context Protocol (MCP) server designed for interacting with the Dixa API, providing streamlined access to conversational data artifacts and administrative tooling.

Core Capabilities

• Data Retrieval Resources
• Query conversations based on specified criteria
• Fetch comprehensive details for an individual conversation
• Access historical notes associated with a dialogue
• Retrieve sequential message history

• List all currently defined system tags

• Action Tools

• Apply new labels/tags to active or completed conversations
• Detach existing labels/tags from conversational threads

Implementation Blueprint

/src ├── dixa-server.ts # Primary server bootstrapping and routing logic ├── config-setup.ts # Environment variable loading and validation ├── data-contracts.ts # TypeScript interfaces and schema definitions ├── handlers/ # Logic modules for resource endpoints └── actions/ # Modules containing executable tool operations

Runtime Configuration Requirements

The gateway necessitates the following environment configuration variables:

• DIXA_API_KEY: Essential credential for authenticating against the Dixa service.
• DIXA_API_BASE_URL (Optional): Allows overriding the default endpoint (defaults to 'https://dev.dixa.io/v1').

Deployment & Testing

1. Environment Setup: bash export DIXA_API_KEY='your-secret-token'

2. Server Launch: bash npm run start-gateway

Validation and Inspection

Rapid Prototyping with mcp-cli

For iterative testing and immediate validation, utilize the fastmcp dev utility:

bash npx fastmcp dev service-entrypoint.ts

Visual Inspection via Web UI

Use the official MCP Inspector for a graphical view of server operations:

bash npx fastmcp inspect dixa-server.ts

Integration with Claude Desktop

To connect this service instance with the Claude Desktop environment, configure your client using the following structure:

{ "mcpServers": { "dixa-portal": { "command": "npx", "args": [ "tsx", "/ABSOLUTE/PATH/TO/YOUR_PROJECT/src/dixa-server.ts" ], "env": { "DIXA_API_KEY": "REPLACE_WITH_ACTUAL_KEY" } } } }

Development Guidelines

Introducing a New Data Retrieval Path

1. Define necessary input/output structures in src/data-contracts.ts.
2. Implement the core retrieval logic within a new file in src/handlers/.
3. Register the new resource handler within src/dixa-server.ts.

Example Handler Snippet: typescript export const fetchAuditLog = { uri: "dixa://audit-log", name: "Conversation Audit Log Fetcher", description: "Retrieves historical events for a specified conversation ID.", execute: async (params: AuditFetchArgs, authContext: AuthCredentials) => { // API call implementation details... } };

Implementing a New Administrative Action

1. Create the action function in src/actions/.
2. Integrate the action into the main server manifest in src/dixa-server.ts.

Example Tool Snippet: typescript export const archiveConversation = { name: "Archive Thread", description: "Marks a conversation as archived in the Dixa system.", invoke: async (input: ArchiveInput, credentials: AuthCredentials) => { // Action execution logic... } };

Exception Management

This implementation formalizes error reporting using specialized classes: - DixaPlatformError: Base class for all Dixa API communication failures. - DataSchemaViolationError: Specific error signaling issues during input or output validation.

Community Showcase

[!TIP] If you have successfully deployed a server using this FastMCP foundation, kindly contribute a link via a pull request to the main repository to be featured here!

• https://github.com/other-project/service-one
• https://github.com/another-project/service-two

Attribution & Inspiration

• The foundational principles of FastMCP stem from the original Python accelerator by Jonathan Lowin.
• Architectural patterns benefited from insights gained while working with LiteMCP.
• Concepts related to streaming data transfer were adapted from explorations documented in Japanese MCP articles.

Contribution Guidelines

1. Adhere strictly to established conventions for resource and action definitions.
2. Ensure comprehensive JSDoc documentation is applied across all public interfaces.
3. Leverage shared utilities provided in data-contracts.ts and config-setup.ts.
4. Update this README file to reflect any significant feature additions.