@firfi/huly-mcp 0.1.0

package/dist/src/huly/errors.js

@@ -0,0 +1,108 @@
+/**
+ * Error hierarchy for Huly MCP server.
+ *
+ * Tagged errors for pattern matching in Effect code.
+ * Maps to MCP error codes:
+ * - -32602 (Invalid params): IssueNotFoundError, ProjectNotFoundError, InvalidStatusError
+ * - -32603 (Internal error): HulyConnectionError, HulyAuthError, HulyError
+ *
+ * @module
+ */
+import { Schema } from "effect";
+/**
+ * MCP standard error codes.
+ */
+export const McpErrorCode = {
+    InvalidParams: -32602,
+    InternalError: -32603,
+};
+/**
+ * Base Huly error - generic operational error.
+ * Maps to MCP -32603 (Internal error).
+ */
+export class HulyError extends Schema.TaggedError()("HulyError", {
+    message: Schema.String,
+    cause: Schema.optional(Schema.Defect),
+}) {
+    mcpErrorCode = McpErrorCode.InternalError;
+}
+/**
+ * Connection error - network/transport failures.
+ * Maps to MCP -32603 (Internal error).
+ */
+export class HulyConnectionError extends Schema.TaggedError()("HulyConnectionError", {
+    message: Schema.String,
+    cause: Schema.optional(Schema.Defect),
+}) {
+    mcpErrorCode = McpErrorCode.InternalError;
+}
+/**
+ * Authentication error - invalid credentials or expired session.
+ * Maps to MCP -32603 (Internal error).
+ */
+export class HulyAuthError extends Schema.TaggedError()("HulyAuthError", {
+    message: Schema.String,
+}) {
+    mcpErrorCode = McpErrorCode.InternalError;
+}
+/**
+ * Issue not found in the specified project.
+ * Maps to MCP -32602 (Invalid params).
+ */
+export class IssueNotFoundError extends Schema.TaggedError()("IssueNotFoundError", {
+    identifier: Schema.String,
+    project: Schema.String,
+}) {
+    mcpErrorCode = McpErrorCode.InvalidParams;
+    get message() {
+        return `Issue '${this.identifier}' not found in project '${this.project}'`;
+    }
+}
+/**
+ * Project not found in the workspace.
+ * Maps to MCP -32602 (Invalid params).
+ */
+export class ProjectNotFoundError extends Schema.TaggedError()("ProjectNotFoundError", {
+    identifier: Schema.String,
+}) {
+    mcpErrorCode = McpErrorCode.InvalidParams;
+    get message() {
+        return `Project '${this.identifier}' not found`;
+    }
+}
+/**
+ * Invalid status for the given project.
+ * Maps to MCP -32602 (Invalid params).
+ */
+export class InvalidStatusError extends Schema.TaggedError()("InvalidStatusError", {
+    status: Schema.String,
+    project: Schema.String,
+}) {
+    mcpErrorCode = McpErrorCode.InvalidParams;
+    get message() {
+        return `Invalid status '${this.status}' for project '${this.project}'`;
+    }
+}
+/**
+ * Person (assignee) not found.
+ * Maps to MCP -32602 (Invalid params).
+ */
+export class PersonNotFoundError extends Schema.TaggedError()("PersonNotFoundError", {
+    identifier: Schema.String,
+}) {
+    mcpErrorCode = McpErrorCode.InvalidParams;
+    get message() {
+        return `Person '${this.identifier}' not found`;
+    }
+}
+/**
+ * Schema for all Huly domain errors (for serialization).
+ */
+export const HulyDomainError = Schema.Union(HulyError, HulyConnectionError, HulyAuthError, IssueNotFoundError, ProjectNotFoundError, InvalidStatusError, PersonNotFoundError);
+/**
+ * Get MCP error code from a Huly domain error.
+ */
+export const getMcpErrorCode = (error) => {
+    return error.mcpErrorCode;
+};
+//# sourceMappingURL=errors.js.map

package/dist/src/huly/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../../src/huly/errors.ts"],"names":[],"mappings":"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"}

package/dist/src/huly/operations/issues.d.ts

@@ -0,0 +1,122 @@
+import { Effect } from "effect";
+import { HulyClient, type HulyClientError } from "../client.js";
+import { ProjectNotFoundError, InvalidStatusError, IssueNotFoundError, PersonNotFoundError } from "../errors.js";
+import type { IssueSummary, ListIssuesParams, GetIssueParams, CreateIssueParams, UpdateIssueParams, AddLabelParams, Issue } from "../../domain/schemas.js";
+/**
+ * Errors that listIssues can produce.
+ */
+export type ListIssuesError = HulyClientError | ProjectNotFoundError | InvalidStatusError;
+/**
+ * Errors that getIssue can produce.
+ */
+export type GetIssueError = HulyClientError | ProjectNotFoundError | IssueNotFoundError;
+/**
+ * Errors that createIssue can produce.
+ */
+export type CreateIssueError = HulyClientError | ProjectNotFoundError | InvalidStatusError | PersonNotFoundError;
+/**
+ * Errors that updateIssue can produce.
+ */
+export type UpdateIssueError = HulyClientError | ProjectNotFoundError | IssueNotFoundError | InvalidStatusError | PersonNotFoundError;
+/**
+ * Errors that addLabel can produce.
+ */
+export type AddLabelError = HulyClientError | ProjectNotFoundError | IssueNotFoundError;
+/**
+ * List issues with filters.
+ *
+ * Filters:
+ * - project (required): Project identifier
+ * - status: "open" | "done" | "canceled" | specific status name
+ * - assignee: Email or person name
+ * - limit: Max results (default 50, max 200)
+ *
+ * Results sorted by modifiedOn descending.
+ */
+export declare const listIssues: (params: ListIssuesParams) => Effect.Effect<IssueSummary[], ListIssuesError, HulyClient>;
+/**
+ * Get a single issue with full details.
+ *
+ * Looks up issue by identifier (e.g., "HULY-123" or just 123).
+ * Returns full issue including:
+ * - Description rendered as markdown
+ * - Assignee name (not just ID)
+ * - Status name
+ * - All metadata
+ *
+ * @param params - Get issue parameters
+ * @returns Full issue object
+ * @throws ProjectNotFoundError if project doesn't exist
+ * @throws IssueNotFoundError if issue doesn't exist in project
+ */
+export declare const getIssue: (params: GetIssueParams) => Effect.Effect<Issue, GetIssueError, HulyClient>;
+/**
+ * Result of createIssue operation.
+ */
+export interface CreateIssueResult {
+    identifier: string;
+}
+/**
+ * Create a new issue in a project.
+ *
+ * Creates issue with:
+ * - Title (required)
+ * - Description (optional, markdown supported)
+ * - Priority (optional, defaults to no-priority)
+ * - Status (optional, uses project default)
+ * - Assignee (optional, by email or name)
+ *
+ * @param params - Create issue parameters
+ * @returns Created issue identifier (e.g., "HULY-123")
+ * @throws ProjectNotFoundError if project doesn't exist
+ * @throws InvalidStatusError if specified status is invalid
+ * @throws PersonNotFoundError if assignee not found
+ */
+export declare const createIssue: (params: CreateIssueParams) => Effect.Effect<CreateIssueResult, CreateIssueError, HulyClient>;
+/**
+ * Result of updateIssue operation.
+ */
+export interface UpdateIssueResult {
+    identifier: string;
+    updated: boolean;
+}
+/**
+ * Update an existing issue in a project.
+ *
+ * Updates only provided fields:
+ * - title: New title
+ * - description: New markdown description (uploaded via uploadMarkup)
+ * - status: New status (resolved by name)
+ * - priority: New priority
+ * - assignee: New assignee email/name, or null to unassign
+ *
+ * @param params - Update issue parameters
+ * @returns Updated issue identifier and success flag
+ * @throws ProjectNotFoundError if project doesn't exist
+ * @throws IssueNotFoundError if issue doesn't exist
+ * @throws InvalidStatusError if specified status is invalid
+ * @throws PersonNotFoundError if assignee not found
+ */
+export declare const updateIssue: (params: UpdateIssueParams) => Effect.Effect<UpdateIssueResult, UpdateIssueError, HulyClient>;
+/**
+ * Result of addLabel operation.
+ */
+export interface AddLabelResult {
+    identifier: string;
+    labelAdded: boolean;
+}
+/**
+ * Add a label/tag to an issue.
+ *
+ * Creates the tag in the project if it doesn't exist,
+ * then attaches it to the issue via TagReference.
+ *
+ * Idempotent: adding the same label twice is a no-op.
+ *
+ * @param params - Add label parameters
+ * @returns Issue identifier and whether label was added
+ * @throws ProjectNotFoundError if project doesn't exist
+ * @throws IssueNotFoundError if issue doesn't exist
+ */
+export declare const addLabel: (params: AddLabelParams) => Effect.Effect<AddLabelResult, AddLabelError, HulyClient>;
+//# sourceMappingURL=issues.d.ts.map

package/dist/src/huly/operations/issues.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"issues.d.ts","sourceRoot":"","sources":["../../../../src/huly/operations/issues.ts"],"names":[],"mappings":"AAaA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAC/B,OAAO,EAAE,UAAU,EAAE,KAAK,eAAe,EAAE,MAAM,cAAc,CAAA;AAC/D,OAAO,EACL,oBAAoB,EACpB,kBAAkB,EAClB,kBAAkB,EAClB,mBAAmB,EACpB,MAAM,cAAc,CAAA;AACrB,OAAO,KAAK,EAAE,YAAY,EAAE,gBAAgB,EAAE,cAAc,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,cAAc,EAAE,KAAK,EAAqC,MAAM,yBAAyB,CAAA;AAgB7L;;GAEG;AACH,MAAM,MAAM,eAAe,GACvB,eAAe,GACf,oBAAoB,GACpB,kBAAkB,CAAA;AAEtB;;GAEG;AACH,MAAM,MAAM,aAAa,GACrB,eAAe,GACf,oBAAoB,GACpB,kBAAkB,CAAA;AAEtB;;GAEG;AACH,MAAM,MAAM,gBAAgB,GACxB,eAAe,GACf,oBAAoB,GACpB,kBAAkB,GAClB,mBAAmB,CAAA;AAEvB;;GAEG;AACH,MAAM,MAAM,gBAAgB,GACxB,eAAe,GACf,oBAAoB,GACpB,kBAAkB,GAClB,kBAAkB,GAClB,mBAAmB,CAAA;AAEvB;;GAEG;AACH,MAAM,MAAM,aAAa,GACrB,eAAe,GACf,oBAAoB,GACpB,kBAAkB,CAAA;AAuEtB;;;;;;;;;;GAUG;AACH,eAAO,MAAM,UAAU,GACrB,QAAQ,gBAAgB,KACvB,MAAM,CAAC,MAAM,CAAC,YAAY,EAAE,EAAE,eAAe,EAAE,UAAU,CA8IxD,CAAA;AA8FJ;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,QAAQ,GACnB,QAAQ,cAAc,KACrB,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,aAAa,EAAE,UAAU,CA0G7C,CAAA;AAIJ;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,UAAU,EAAE,MAAM,CAAA;CACnB;AAED;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,WAAW,GACtB,QAAQ,iBAAiB,KACxB,MAAM,CAAC,MAAM,CAAC,iBAAiB,EAAE,gBAAgB,EAAE,UAAU,CAgI5D,CAAA;AAIJ;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,UAAU,EAAE,MAAM,CAAA;IAClB,OAAO,EAAE,OAAO,CAAA;CACjB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,WAAW,GACtB,QAAQ,iBAAiB,KACxB,MAAM,CAAC,MAAM,CAAC,iBAAiB,EAAE,gBAAgB,EAAE,UAAU,CAoI5D,CAAA;AAIJ;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,MAAM,CAAA;IAClB,UAAU,EAAE,OAAO,CAAA;CACpB;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,QAAQ,GACnB,QAAQ,cAAc,KACrB,MAAM,CAAC,MAAM,CAAC,cAAc,EAAE,aAAa,EAAE,UAAU,CA6HtD,CAAA"}