@selfagency/beans-mcp 0.1.0

package/index.d.ts

@@ -0,0 +1,219 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+
+/**
+ * Public types for beans-mcp-server
+ */
+type SortMode = "status-priority-type-title" | "updated" | "created" | "id";
+type BeanRecord = {
+    id: string;
+    slug: string;
+    path: string;
+    title: string;
+    body: string;
+    status: string;
+    type: string;
+    description?: string;
+    priority?: string;
+    tags?: string[];
+    parentId?: string;
+    blockingIds?: string[];
+    blockedByIds?: string[];
+    createdAt?: string;
+    updatedAt?: string;
+    etag?: string;
+};
+/**
+ * GraphQL error shape as returned by the Beans CLI GraphQL endpoint.
+ */
+type GraphQLError = {
+    message: string;
+    locations?: Array<{
+        line: number;
+        column: number;
+    }>;
+    path?: Array<string | number>;
+    extensions?: Record<string, unknown>;
+};
+declare const DEFAULT_MCP_PORT = 39173;
+declare const MAX_ID_LENGTH = 128;
+declare const MAX_TITLE_LENGTH = 1024;
+declare const MAX_METADATA_LENGTH = 128;
+
+declare function sortBeansInternal(beans: BeanRecord[], mode: SortMode): BeanRecord[];
+
+/**
+ * Interface for backend implementations.
+ * Allows for alternative implementations (e.g., test harnesses).
+ */
+interface BackendInterface {
+    init(prefix?: string): Promise<Record<string, unknown>>;
+    list(options?: {
+        status?: string[];
+        type?: string[];
+        search?: string;
+    }): Promise<BeanRecord[]>;
+    create(input: {
+        title: string;
+        type: string;
+        status?: string;
+        priority?: string;
+        description?: string;
+        parent?: string;
+    }): Promise<BeanRecord>;
+    update(beanId: string, updates: {
+        status?: string;
+        type?: string;
+        priority?: string;
+        parent?: string;
+        clearParent?: boolean;
+        blocking?: string[];
+        blockedBy?: string[];
+    }): Promise<BeanRecord>;
+    delete(beanId: string): Promise<Record<string, unknown>>;
+    openConfig(): Promise<{
+        configPath: string;
+        content: string;
+    }>;
+    graphqlSchema(): Promise<string>;
+    readOutputLog(options?: {
+        lines?: number;
+    }): Promise<{
+        path: string;
+        content: string;
+        linesReturned: number;
+    }>;
+    readBeanFile(relativePath: string): Promise<{
+        path: string;
+        content: string;
+    }>;
+    editBeanFile(relativePath: string, content: string): Promise<{
+        path: string;
+        bytes: number;
+    }>;
+    createBeanFile(relativePath: string, content: string, options?: {
+        overwrite?: boolean;
+    }): Promise<{
+        path: string;
+        bytes: number;
+        created: boolean;
+    }>;
+    deleteBeanFile(relativePath: string): Promise<{
+        path: string;
+        deleted: boolean;
+    }>;
+}
+/**
+ * Beans CLI backend implementation.
+ * Wraps the Beans CLI and provides a typed interface for MCP tools.
+ */
+declare class BeansCliBackend implements BackendInterface {
+    private readonly workspaceRoot;
+    private readonly cliPath;
+    private readonly logDir?;
+    constructor(workspaceRoot: string, cliPath: string, logDir?: string | undefined);
+    /**
+     * Returns a safe environment for executing the Beans CLI,
+     * whitelisting only necessary variables.
+     */
+    private getSafeEnv;
+    private getBeansRoot;
+    private resolveBeanFilePath;
+    /**
+     * Execute a GraphQL query via the Beans CLI.
+     */
+    private executeGraphQL;
+    init(prefix?: string): Promise<Record<string, unknown>>;
+    list(options?: {
+        status?: string[];
+        type?: string[];
+        search?: string;
+    }): Promise<BeanRecord[]>;
+    create(input: {
+        title: string;
+        type: string;
+        status?: string;
+        priority?: string;
+        description?: string;
+        parent?: string;
+    }): Promise<BeanRecord>;
+    update(beanId: string, updates: {
+        status?: string;
+        type?: string;
+        priority?: string;
+        parent?: string;
+        clearParent?: boolean;
+        blocking?: string[];
+        blockedBy?: string[];
+    }): Promise<BeanRecord>;
+    delete(beanId: string): Promise<Record<string, unknown>>;
+    openConfig(): Promise<{
+        configPath: string;
+        content: string;
+    }>;
+    graphqlSchema(): Promise<string>;
+    readOutputLog(options?: {
+        lines?: number;
+    }): Promise<{
+        path: string;
+        content: string;
+        linesReturned: number;
+    }>;
+    readBeanFile(relativePath: string): Promise<{
+        path: string;
+        content: string;
+    }>;
+    editBeanFile(relativePath: string, content: string): Promise<{
+        path: string;
+        bytes: number;
+    }>;
+    createBeanFile(relativePath: string, content: string, options?: {
+        overwrite?: boolean;
+    }): Promise<{
+        path: string;
+        bytes: number;
+        created: boolean;
+    }>;
+    deleteBeanFile(relativePath: string): Promise<{
+        path: string;
+        deleted: boolean;
+    }>;
+}
+
+declare function createBeansMcpServer(opts: {
+    workspaceRoot: string;
+    cliPath?: string;
+    name?: string;
+    version?: string;
+    logDir?: string;
+    backend?: BackendInterface;
+}): Promise<{
+    server: McpServer;
+    backend: BackendInterface;
+}>;
+declare function parseCliArgs(argv: string[]): {
+    workspaceRoot: string;
+    /** True when the caller explicitly supplied --workspace-root (or the positional arg). */
+    workspaceExplicit: boolean;
+    cliPath: string;
+    port: number;
+    logDir?: string;
+};
+declare function startBeansMcpServer(argv: string[], 
+/** For testing only: override the roots resolver so tests can cover the setInner branch. */
+_resolveRoots?: (server: McpServer) => Promise<string | null>): Promise<void>;
+
+/**
+ * Check whether `target` is contained within `root` after resolving both paths.
+ * Guards against the Windows cross-drive bypass where `path.relative(root, target)`
+ * returns an absolute path (e.g. `D:\evil`) that does not start with `..`.
+ */
+declare function isPathWithinRoot(root: string, target: string): boolean;
+declare function makeTextAndStructured<T extends Record<string, unknown>>(value: T): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    structuredContent: T;
+};
+
+export { type BackendInterface, type BeanRecord, BeansCliBackend, DEFAULT_MCP_PORT, type GraphQLError, MAX_ID_LENGTH, MAX_METADATA_LENGTH, MAX_TITLE_LENGTH, type SortMode, createBeansMcpServer, isPathWithinRoot, makeTextAndStructured, parseCliArgs, sortBeansInternal as sortBeans, startBeansMcpServer };