equip_item
Equip a pet, mount, costume, or battle gear in Habitica using the item's key. Specify the type to assign equipment to your avatar.
Instructions
Equip a pet, mount, costume piece, or battle gear.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| type | Yes | ||
| key | Yes |
Implementation Reference
- index.js:283-294 (schema)Input schema definition for equip_item tool: requires 'type' (enum: pet, mount, costume, or equipped) and 'key' (string).
{ name: "equip_item", description: "Equip a pet, mount, costume piece, or battle gear.", inputSchema: { type: "object", properties: { type: { type: "string", enum: ["pet", "mount", "costume", "equipped"] }, key: { type: "string" }, }, required: ["type", "key"], }, }, - index.js:441-444 (handler)Handler function for equip_item: calls Habitica API POST /user/equip/{type}/{key} to equip a pet, mount, costume piece, or battle gear.
equip_item: async ({ type, key }) => { await api("POST", `/user/equip/${type}/${encodeURIComponent(key)}`); return ok(`Equipped ${type}: ${key}`); }, - index.js:480-480 (registration)Tools array is registered with the MCP server via ListToolsRequestSchema handler.
server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools })); - index.js:482-492 (registration)CallToolRequestSchema handler dispatches incoming tool calls to the handlers object (including equip_item).
server.setRequestHandler(CallToolRequestSchema, async (req) => { const { name, arguments: args = {} } = req.params; const fn = handlers[name]; if (!fn) throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${name}`); try { return await fn(args); } catch (err) { if (err instanceof McpError) throw err; throw new McpError(ErrorCode.InternalError, err?.message ?? String(err)); } }); - index.js:23-51 (helper)The api() helper function used by equip_item to make HTTP requests to the Habitica API.
async function api(method, path, body) { const url = `${API_BASE}${path}`; const headers = { "x-api-user": USER_ID, "x-api-key": API_TOKEN, "x-client": `${USER_ID}-${APP_ID}`, "Content-Type": "application/json", }; const res = await fetch(url, { method, headers, body: body === undefined ? undefined : JSON.stringify(body), }); const text = await res.text(); let payload; try { payload = text ? JSON.parse(text) : {}; } catch { payload = { raw: text }; } if (!res.ok) { const msg = payload?.message || payload?.error || res.statusText; throw new McpError( ErrorCode.InternalError, `Habitica API ${res.status}: ${msg}`, ); } return payload; }