mcp-server

Files (7)

• SKILL.md
• mcp-config.md · docs/
• permissions.md · docs/
• evaluation.md · reference/
• mcp_best_practices.md · reference/
• node_mcp_server.md · reference/
• python_mcp_server.md · reference/

SKILL.md (first lines)

# MCP Server Development Guide for DAX

## Overview

MCP (Model Context Protocol) servers extend DAX's capabilities by adding custom tools that connect to external APIs and services. This skill guides you through creating high-quality MCP servers that integrate seamlessly with DAX's governance and execution model.

When you create an MCP server for DAX:

- Tools automatically integrate with DAX's tool pipeline
- Each tool call goes through DAX's approval system (RAO contract)
- Tool usage is tracked in the audit ledger
- You can configure per-tool permissions in `dax.json`

---

## Process

### Phase 1: Research and Planning

#### 1.1 Understand MCP Design Principles

**API Coverage vs. Workflow Tools:**

- Prioritize comprehensive API coverage for flexibility
- Add specialized workflow tools for common tasks
- DAX agents can compose operations across multiple tools

**Tool Naming:**

- Use clear, descriptive names with consistent prefixes
- Example: `github_create_issue`, `filesystem_read_file`
- Helps DAX's intent classification match tools to user needs

**Tool Descriptions:**

- Write concise descriptions (1-2 sentences)
- Include parameter descriptions
- DAX uses descriptions for tool selection

**Error Handling:**

- Provide actionable error messages with specific suggestions
- DAX will surface errors through its verification system

#### 1.2 Study MCP Protocol

**Key Resources:**

- MCP Specification: `https://modelcontextprotocol.io/specification/draft.md`
- Best Practices: [MCP Best Practices](./reference/mcp_best_practices.md)

#### 1.3 Choose Your Stack

| Language       | SDK                       | Best For                           |
| -------------- | ------------------------- | ---------------------------------- |
| **TypeScript** | @modelcontextprotocol/sdk | Node.js projects, type safety      |
| **Python**     | mcp                       | FastMCP, data science integrations |

**Transport Selection:**

- **stdio**: Local servers, testing
- **streamable-http**: Production, remote servers

---

### Phase 2: Implementation

#### 2.1 Project Setup

**TypeScript:**

```bash
mkdir my-mcp-server && cd my-mcp-server
npm init -y
npm install @modelcontextprotocol/sdk @modelcontextprotocol/server-filesystem
```

**Python:**

```bash
pip install mcp fastmcp
```

#### 2.2 Core Infrastructure

Create utilities for:

- API client with authentication
- Error handling
- Response formatting
- Pagination

#### 2.3 Implement Tools

For each tool, define:

**Input Schema (TypeScript with Zod):**

```typescript
{
  name: "create_issue",
  description: "Create a new GitHub issue",
  inputSchema: z.object({
    title: z.string().describe("Issue title"),
    body: z.string().optional().describe("Issue body"),
    labels: z.array(z.string()).optional().describe("Labels to apply"),
  })
}
```

**Annotations (important for DAX governance):**

- `readOnlyHint`: true/false - Read-only vs mutating operations
- `destructiveHint`: true/false - Potentially destructive actions
- `idempotentHint`: true/false - Safe to retry

DAX uses these hints to determine approval requirements.

---

From ShaileshRawat1403/dax, MIT.

More from ShaileshRawat1403/dax