Terraform Cloud MCP Server

Instructions

Implementation Reference

• src/index.ts:189-219 (handler)

  The handler function that implements the logic for the 'get_workspace_details' tool by fetching workspace data from the Terraform Cloud API using tfCloudRequest and formatting the output.

  async ({ workspaceName, organization }) => {
    try {
      const data = await tfCloudRequest(`/organizations/${organization}/workspaces/${workspaceName}`);
      const attrs = data.data.attributes;
      
      const output = {
        id: data.data.id,
        name: attrs.name,
        locked: attrs.locked,
        executionMode: attrs['execution-mode'],
        autoApply: attrs['auto-apply'],
        terraformVersion: attrs['terraform-version'],
        workingDirectory: attrs['working-directory'] || undefined,
        vcsRepo: attrs['vcs-repo'] ? {
          identifier: attrs['vcs-repo'].identifier,
          branch: attrs['vcs-repo'].branch
        } : 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:168-188 (schema)

  Zod schema definitions for input (workspaceName, organization) and output fields of the get_workspace_details tool.

  {
    title: 'Get Workspace Details',
    description: 'Get detailed information about a Terraform Cloud workspace',
    inputSchema: {
      workspaceName: z.string().describe('Workspace name'),
      organization: z.string().default('urbanmedia').describe('Organization name')
    },
    outputSchema: {
      id: z.string(),
      name: z.string(),
      locked: z.boolean(),
      executionMode: z.string(),
      autoApply: z.boolean(),
      terraformVersion: z.string(),
      workingDirectory: z.string().optional(),
      vcsRepo: z.object({
        identifier: z.string(),
        branch: z.string()
      }).optional()
    }
  },

• src/index.ts:166-220 (registration)

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

  server.registerTool(
    'get_workspace_details',
    {
      title: 'Get Workspace Details',
      description: 'Get detailed information about a Terraform Cloud workspace',
      inputSchema: {
        workspaceName: z.string().describe('Workspace name'),
        organization: z.string().default('urbanmedia').describe('Organization name')
      },
      outputSchema: {
        id: z.string(),
        name: z.string(),
        locked: z.boolean(),
        executionMode: z.string(),
        autoApply: z.boolean(),
        terraformVersion: z.string(),
        workingDirectory: z.string().optional(),
        vcsRepo: z.object({
          identifier: z.string(),
          branch: z.string()
        }).optional()
      }
    },
    async ({ workspaceName, organization }) => {
      try {
        const data = await tfCloudRequest(`/organizations/${organization}/workspaces/${workspaceName}`);
        const attrs = data.data.attributes;
        
        const output = {
          id: data.data.id,
          name: attrs.name,
          locked: attrs.locked,
          executionMode: attrs['execution-mode'],
          autoApply: attrs['auto-apply'],
          terraformVersion: attrs['terraform-version'],
          workingDirectory: attrs['working-directory'] || undefined,
          vcsRepo: attrs['vcs-repo'] ? {
            identifier: attrs['vcs-repo'].identifier,
            branch: attrs['vcs-repo'].branch
          } : 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:25-39 (helper)

  Helper function used by the tool to make authenticated API requests to Terraform Cloud.

  async function tfCloudRequest(endpoint: string): Promise<any> {
    const token = getTerraformToken();
    const response = await fetch(`${TF_API_BASE}${endpoint}`, {
      headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/vnd.api+json'
      }
    });
  
    if (!response.ok) {
      throw new Error(`Terraform Cloud API error: ${response.statusText}`);
    }
  
    return response.json();
  }