Terraform Cloud MCP Server

Instructions

Implementation Reference

• src/index.ts:252-290 (handler)

  The asynchronous handler function that executes the tool logic: fetches run details from Terraform Cloud API using tfCloudRequest, processes the data, and returns formatted structured content or error.

      try {
        const data = await tfCloudRequest(`/runs/${runId}`);
        const attrs = data.data.attributes;
        const relationships = data.data.relationships;
  
        const output = {
          id: data.data.id,
          status: attrs.status,
          message: attrs.message || 'No message',
          createdAt: attrs['created-at'],
          source: attrs.source,
          isConfirmable: attrs['is-confirmable'],
          hasChanges: attrs['has-changes'],
          planStatus: attrs['plan-status'] || undefined,
          applyStatus: attrs['apply-status'] || undefined,
          workspace: {
            id: relationships.workspace.data.id,
            name: attrs['workspace-name'] || 'Unknown'
          },
          configurationVersion: relationships['configuration-version']?.data ? {
            id: relationships['configuration-version'].data.id,
            source: attrs['configuration-version-source'] || 'Unknown'
          } : undefined
        };
  
        return {
          content: [{ type: 'text', text: JSON.stringify(output, null, 2) }],
          structuredContent: output
        };
      } catch (error) {
        const errorMsg = error instanceof Error ? error.message : String(error);
        return {
          content: [{ type: 'text', text: `Error: ${errorMsg}` }],
          isError: true
        };
      }
    }
  );

• src/index.ts:225-251 (schema)

  Zod-based inputSchema (requires runId) and outputSchema defining the expected tool input/output structures.

  {
    title: 'Get Run Details',
    description: 'Get detailed information about a specific Terraform Cloud run by its ID',
    inputSchema: {
      runId: z.string().describe('Run ID (e.g., run-abc123)')
    },
    outputSchema: {
      id: z.string(),
      status: z.string(),
      message: z.string(),
      createdAt: z.string(),
      source: z.string(),
      isConfirmable: z.boolean(),
      hasChanges: z.boolean(),
      planStatus: z.string().optional(),
      applyStatus: z.string().optional(),
      workspace: z.object({
        id: z.string(),
        name: z.string()
      }),
      configurationVersion: z.object({
        id: z.string(),
        source: z.string()
      }).optional()
    }
  },
  async ({ runId }) => {

• src/index.ts:223-291 (registration)

  The server.registerTool call that registers the 'get_run_details' tool with its schema and handler function.

  server.registerTool(
    'get_run_details',
    {
      title: 'Get Run Details',
      description: 'Get detailed information about a specific Terraform Cloud run by its ID',
      inputSchema: {
        runId: z.string().describe('Run ID (e.g., run-abc123)')
      },
      outputSchema: {
        id: z.string(),
        status: z.string(),
        message: z.string(),
        createdAt: z.string(),
        source: z.string(),
        isConfirmable: z.boolean(),
        hasChanges: z.boolean(),
        planStatus: z.string().optional(),
        applyStatus: z.string().optional(),
        workspace: z.object({
          id: z.string(),
          name: z.string()
        }),
        configurationVersion: z.object({
          id: z.string(),
          source: z.string()
        }).optional()
      }
    },
    async ({ runId }) => {
      try {
        const data = await tfCloudRequest(`/runs/${runId}`);
        const attrs = data.data.attributes;
        const relationships = data.data.relationships;
  
        const output = {
          id: data.data.id,
          status: attrs.status,
          message: attrs.message || 'No message',
          createdAt: attrs['created-at'],
          source: attrs.source,
          isConfirmable: attrs['is-confirmable'],
          hasChanges: attrs['has-changes'],
          planStatus: attrs['plan-status'] || undefined,
          applyStatus: attrs['apply-status'] || undefined,
          workspace: {
            id: relationships.workspace.data.id,
            name: attrs['workspace-name'] || 'Unknown'
          },
          configurationVersion: relationships['configuration-version']?.data ? {
            id: relationships['configuration-version'].data.id,
            source: attrs['configuration-version-source'] || 'Unknown'
          } : undefined
        };
  
        return {
          content: [{ type: 'text', text: JSON.stringify(output, null, 2) }],
          structuredContent: output
        };
      } catch (error) {
        const errorMsg = error instanceof Error ? error.message : String(error);
        return {
          content: [{ type: 'text', text: `Error: ${errorMsg}` }],
          isError: true
        };
      }
    }
  );
  
  // Connect to stdio transport