Coyote MCP Server

An MCP (Model Context Protocol) server that lets you manage Coyote worklogs, tasks, and issues from Claude Code or Claude Desktop using natural language.

This repository is the development source for the server. End users do not install from here — the server is published to npm and run via npx:

claude mcp add coyote -s user -- npx -y @yata-technologies/coyote-mcp@latest

(See the internal install guide for the full end-user setup — Claude Desktop config, authentication, etc.)

The rest of this document is for developers working on Coyote MCP. See CLAUDE.md for the full architecture, API spec, and conventions.

How it works

User → natural language → Claude Code / Claude Desktop
                              ↓ MCP tool call (stdio)
                       Coyote MCP Server (this package, runs locally)
                              ↓ Bearer coy_xxx
                       Coyote Worker API (Cloudflare Workers)
                              ↓ SQL
                       D1 Database (Cloudflare)

The server runs on the user's machine and talks to Claude over stdio. It calls the Coyote API (https://api.coyote-worklog.com) with a Bearer token stored at ~/.coyote/token.

Repository layout

/
├── CLAUDE.md            Architecture, API spec, conventions (read this first)
├── README.md            This file
├── package.json         Version source of truth
├── tsconfig.json
└── src/
    ├── index.ts         Entry point (server start / `login` command, tool dispatch)
    ├── lib/
    │   ├── client.ts    HTTP client (Bearer auth, GET/POST/PUT/DELETE)
    │   └── token.ts     read/write ~/.coyote/token
    └── tools/           one file per resource (auth, tasks, issues, worklogs, comments, …)

Development setup

git clone [email protected]:yata-technologies/coyote-mcp.git
cd coyote-mcp
npm install
npm run build      # tsc → dist/

node_modules is not tracked. Always run npm install after cloning or pulling, otherwise the server fails to start with a module-resolution error.

Run your local build

Register your clone in ~/.claude.json (Claude Code), pointing at the compiled entry point:

{
  "mcpServers": {
    "coyote": {
      "command": "node",
      "args": ["/absolute/path/to/coyote-mcp/dist/index.js"]
    }
  }
}

Restart Claude Code to pick it up. Use npm run dev (tsc --watch) while iterating, then restart the client to load the rebuilt dist/. Update your clone manually with git pull && npm run build — the server no longer touches git on startup (the old clone-era auto-update was removed in COY-318).

Authenticate the same way users do — ask "Login to Coyote" in chat, or from the CLI:

node dist/index.js login

If you also have the npm version registered, remove it first so you don't run two coyote servers: claude mcp remove coyote -s user.

Scripts

| Command | Purpose | |---|---| | npm run build | Compile TypeScript → dist/ | | npm run dev | tsc --watch for local iteration | | npm run clean | Remove dist/ | | npm run prepublishOnly | Runs automatically before npm publish (rebuilds dist/) |

Adding a tool

1. Add the tool definition (inputSchema) and handler to a file in src/tools/ (new file or existing one).
2. Export the tool definition and handler.
3. Import them in src/index.ts, add the tool to ALL_TOOLS and the matching Set.
4. Wire the handler into the CallToolRequestSchema dispatch.

Tool names follow coyote_<verb>_<resource> (list/get/create/update/delete). See CLAUDE.md for naming rules and the Coyote API reference.

Distribution is npm/npx only — the .mcpb bundle and manifest.json were retired in COY-263, so there's no manifest sync step anymore.

Versioning

Every PR bumps the version — patch or higher, regardless of whether it's a fix, feature, refactor, or docs change. npm is the single source of distribution (@latest), so the bump is what ships the change.

| File | How | |---|---| | package.json | Bump version manually | | src/index.ts | Reads from package.json — no change needed |

Releasing

Publishing is automated. On push to main, .github/workflows/release.yml compares package.json's version against the npm registry and runs npm publish only when it's a new version (a forgotten bump simply skips; a re-run never errors on a duplicate). prepublishOnly rebuilds dist/, and the npm tarball ships dist/ only (files: ["dist"] — this README is not published).

So: merge a version-bumped PR to main, and the new version goes live on npm automatically. Users on @latest pick it up on their next client restart.

Available tools

| Category | Tools | |---|---| | Auth | coyote_login, coyote_login_complete, coyote_get_me, coyote_update_me, coyote_upgrade | | Projects | coyote_list_projects, coyote_get_project, coyote_create_project, coyote_update_project, coyote_delete_project, coyote_list_members | | Members | coyote_add_member, coyote_update_member_role, coyote_remove_member | | Issues | coyote_list_issues, coyote_get_issue, coyote_create_issue, coyote_update_issue, coyote_delete_issue | | Tasks | coyote_list_tasks, coyote_get_task, coyote_create_task, coyote_update_task, coyote_delete_task | | Worklogs | coyote_list_worklogs, coyote_get_worklog, coyote_create_worklog, coyote_update_worklog, coyote_delete_worklog | | Comments | coyote_list_comments, coyote_create_comment, coyote_update_comment, coyote_delete_comment | | Sprints | coyote_list_sprints, coyote_get_sprint, coyote_get_current_sprint, coyote_create_sprint, coyote_update_sprint, coyote_delete_sprint | | Patterns | coyote_list_patterns, coyote_get_pattern, coyote_create_pattern, coyote_update_pattern, coyote_delete_pattern | | Categories | coyote_list_categories, coyote_create_category, coyote_update_category, coyote_delete_category | | Phases | coyote_list_phases, coyote_create_phase, coyote_update_phase, coyote_delete_phase | | Activities | coyote_list_activities, coyote_get_activity, coyote_create_activity, coyote_update_activity, coyote_delete_activity | | Users | coyote_list_users, coyote_get_user, coyote_update_user, coyote_deactivate_user, coyote_reactivate_user | | Vendors | coyote_list_vendors, coyote_create_vendor, coyote_update_vendor, coyote_delete_vendor |

Local files (user machine)

| Path | Contents | |---|---| | ~/.coyote/token | API token (coy_xxx), permission 0600. Windows: %USERPROFILE%\.coyote\token | | ~/.claude.json | MCP server registration (Claude Code) |

Security

Found a vulnerability? Please report it privately via GitHub Security Advisories rather than opening a public issue. See SECURITY.md for details.

License and Trademarks

Released under the MIT License — see LICENSE.

"Coyote" and "YATA Technologies" are trademarks of YATA Technologies. The MIT license covers the source code in this repository; it does not grant permission to use these names or logos in ways that suggest endorsement by, or affiliation with, YATA Technologies.