README.md•3.84 kB
# Dixa MCP Server
A FastMCP server implementation for the Dixa API, providing resources and tools for managing conversations and tags.
## Features
- **Resources**
- Search conversations
- Get conversation details
- Get conversation notes
- Get conversation messages
- Get available tags
- **Tools**
- Add tags to conversations
- Remove tags from conversations
## Project Structure
```
/src
├── dixa.ts # Main server setup
├── config.ts # Configuration and environment settings
├── types.ts # Shared types and error handling
├── resources/ # Resource implementations
├── schemas/ # Zod schemas for validation
└── tools/ # Tool implementations
```
## Configuration
The server requires the following environment variables:
- `DIXA_API_KEY`: Your Dixa API key
- `DIXA_API_BASE_URL` (optional): Override the default API URL (defaults to 'https://dev.dixa.io/v1')
## Usage
1. Set up environment variables:
```bash
export DIXA_API_KEY='your-api-key'
```
2. Start the server:
```bash
npm start
```
## Running Your Server
### Test with `mcp-cli`
The fastest way to test and debug your server is with `fastmcp dev`:
```bash
npx fastmcp dev server.js
npx fastmcp dev server.ts
```
This will run your server with [`mcp-cli`](https://github.com/wong2/mcp-cli) for testing and debugging your MCP server in the terminal.
### Inspect with `MCP Inspector`
Another way is to use the official [`MCP Inspector`](https://modelcontextprotocol.io/docs/tools/inspector) to inspect your server with a Web UI:
```bash
npx fastmcp inspect server.ts
```
## FAQ
### How to use with Claude Desktop?
Follow the guide https://modelcontextprotocol.io/quickstart/user and add the following configuration:
```json
{
"mcpServers": {
"my-mcp-server": {
"command": "npx",
"args": [
"tsx",
"/PATH/TO/YOUR_PROJECT/src/index.ts"
],
"env": {
"YOUR_ENV_VAR": "value"
}
}
}
}
```
## Development
### Adding a New Resource
1. Create a schema in `src/schemas/`
2. Create the resource in `src/resources/`
3. Add the resource to `src/dixa.ts`
Example resource:
```typescript
export const myResource = {
uri: "dixa://my-resource",
name: "My Resource",
description: "Description",
load: async (args: MyArgs, apiKey: string) => {
// Implementation
}
};
```
### Adding a New Tool
1. Create the tool in `src/tools/`
2. Add the tool to `src/dixa.ts`
Example tool:
```typescript
export const myTool = {
name: "My Tool",
description: "Description",
execute: async (args: MyArgs, apiKey: string) => {
// Implementation
}
};
```
## Error Handling
The project uses custom error classes:
- `DixaError`: Base error class for API errors
- `DixaValidationError`: For response validation failures
## Showcase
> [!NOTE]
>
> If you've developed a server using FastMCP, please [submit a PR](https://github.com/punkpeye/fastmcp) to showcase it here!
- https://github.com/apinetwork/piapi-mcp-server
- https://github.com/Meeting-Baas/meeting-mcp - Meeting BaaS MCP server that enables AI assistants to create meeting bots, search transcripts, and manage recording data
## Acknowledgements
- FastMCP is inspired by the [Python implementation](https://github.com/jlowin/fastmcp) by [Jonathan Lowin](https://github.com/jlowin).
- Parts of codebase were adopted from [LiteMCP](https://github.com/wong2/litemcp).
- Parts of codebase were adopted from [Model Context protocolでSSEをやってみる](https://dev.classmethod.jp/articles/mcp-sse/).
## Contributing
1. Follow the existing patterns for resources and tools
2. Add proper JSDoc documentation
3. Use the shared utilities in `types.ts` and `config.ts`
4. Update the README if adding new features