Skip to content

CLAUDE.md

Latest commit

 

History

History
148 lines (111 loc) · 3.39 KB

CLAUDE.md

File metadata and controls

148 lines (111 loc) · 3.39 KB
Raw

Clink MCP Server - Development Guide

This is the MCP server for Clink, published to npm as @voxos-ai/clink-mcp-server.

Source Location

This code lives in the voxos monorepo at projects/clink/mcp/ and is published to GitHub at:

Publishing to GitHub

This directory is synced to GitHub using git subtree. The GitHub repo is a mirror of this subdirectory.

First-time setup (already done)

# Add the GitHub remote
git remote add github-mcp git@github.com:Voxos-ai-Inc/clink-mcp-server.git

Publishing changes

After making changes to projects/clink/mcp/:

# 1. Commit your changes to the monorepo
git add projects/clink/mcp/
git commit -m "feat(mcp): your change description"

# 2. Push the subdirectory to GitHub
git subtree push --prefix=projects/clink/mcp github-mcp main

Or use the make target:

make mcp-publish

Important notes

  • Always commit to the monorepo first, then push to GitHub
  • The GitHub repo's main branch mirrors this directory
  • Don't edit the GitHub repo directly - changes flow monorepo → GitHub only
  • The .gitignore excludes node_modules/ and dist/ from GitHub

Publishing to npm

After pushing to GitHub:

cd projects/clink/mcp
npm version patch  # or minor/major
npm publish --access public

Then commit the version bump to the monorepo and push to GitHub again.

Development

cd projects/clink/mcp
npm install
npm run build
npm run dev  # watch mode

Testing locally with Claude Code

  1. Build the server: npm run build
  2. Update your ~/.claude.json to use the local build:
{
  "mcpServers": {
    "clink": {
      "command": "node",
      "args": ["/path/to/voxos/projects/clink/mcp/dist/index.js"],
      "env": {
        "CLINK_API_KEY": "sk_live_...",
        "CLINK_API_URL": "https://api.clink.stg.voxos.ai"
      }
    }
  }
}
  1. Restart Claude Code

Project Structure

src/
  index.ts        # MCP server entry point, tool registration
  client.ts       # ClinkClient - HTTP client for Clink API
  types.ts        # TypeScript interfaces
  tools/          # One file per MCP tool
    list_groups.ts
    send_clink.ts
    check_inbox.ts
    ...

Adding a New Tool

  1. Create src/tools/your_tool.ts:
import { ClinkClient } from '../client.js';

export const yourToolDefinition = {
  name: 'your_tool',
  description: 'What this tool does',
  inputSchema: {
    type: 'object' as const,
    properties: {
      param: { type: 'string', description: 'Parameter description' }
    },
    required: ['param']
  }
};

export async function handleYourTool(
  client: ClinkClient,
  args: { param: string }
): Promise<string> {
  const result = await client.yourApiMethod(args.param);
  return JSON.stringify(result, null, 2);
}

  1. Register in src/index.ts:

    • Import the definition and handler
    • Add to tools array
    • Add case in the switch statement

  2. Add the API method to src/client.ts if needed

  3. Build and test: npm run build

API Compatibility

The MCP server must stay compatible with the Clink API. When the API changes:

  1. Update src/types.ts with new interfaces
  2. Update src/client.ts with new/modified methods
  3. Update affected tools in src/tools/
  4. Bump version appropriately (breaking changes = major)