Tool Types¶

Understanding the different types of tools generated by GitHub to MCP.

Overview¶

Tools are the core functionality exposed by MCP servers. GitHub to MCP generates two categories:

Universal Tools - Always included, work with any repository
Extracted Tools - Specific to the repository's API/functionality

Universal Tools¶

These tools are included by default for every repository.

get_readme¶

Fetch the repository's README content.

{
  "name": "get_readme",
  "description": "Get the README content of the repository",
  "inputSchema": {
    "type": "object",
    "properties": {}
  }
}

Use case: Understanding what a project does, finding documentation.

list_files¶

List files and directories in the repository.

{
  "name": "list_files",
  "description": "List files in a directory",
  "inputSchema": {
    "type": "object",
    "properties": {
      "path": {
        "type": "string",
        "description": "Directory path (default: root)"
      },
      "recursive": {
        "type": "boolean",
        "description": "Include subdirectories"
      }
    }
  }
}

Use case: Exploring project structure, finding specific files.

read_file¶

Read the contents of any file.

{
  "name": "read_file",
  "description": "Read the contents of a file",
  "inputSchema": {
    "type": "object",
    "properties": {
      "path": {
        "type": "string",
        "description": "Path to the file"
      }
    },
    "required": ["path"]
  }
}

Use case: Reading source code, configuration files, documentation.

search_code¶

Search for code patterns in the repository.

{
  "name": "search_code",
  "description": "Search for code patterns",
  "inputSchema": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "Search query"
      },
      "path": {
        "type": "string",
        "description": "Limit search to path"
      },
      "extension": {
        "type": "string",
        "description": "File extension filter"
      }
    },
    "required": ["query"]
  }
}

Use case: Finding function definitions, usages, patterns.

Extracted Tools¶

These tools are specific to each repository, extracted from various sources.

From OpenAPI/Swagger¶

API endpoints become callable tools:

Original OpenAPI:

paths:
  /customers:
    post:
      operationId: createCustomer
      summary: Create a new customer
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                name:
                  type: string

Generated Tool:

{
  "name": "create_customer",
  "description": "Create a new customer",
  "inputSchema": {
    "type": "object",
    "properties": {
      "email": { "type": "string" },
      "name": { "type": "string" }
    }
  },
  "source": "openapi"
}

From GraphQL¶

Queries and mutations become tools:

Original GraphQL:

type Query {
  user(id: ID!): User
  users(limit: Int): [User!]!
}

type Mutation {
  createUser(input: CreateUserInput!): User!
}

Generated Tools:

id=__codelineno-7-1 name=__codelineno-7-1 href=#__codelineno-7-1>[ { "name": "query_user", "description": "Get a user by ID", "inputSchema": { "type": "object", "properties": { "id": { "type": "string" } }, "required": ["id"] }, "source": "graphql" }, { "name": "create_user", "description": "Create a new user", "inputSchema": { "type": "object", "properties": { "input": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string" } } } } }, "source": "graphql" } class=p>]

From Python Code¶

Functions with @mcp.tool decorators:

Original Python:

from mcp import tool

@tool
def analyze_text(text: str, language: str = "en") -> dict:
    """Analyze the given text for sentiment and entities."""
    # ...

Generated Tool:

{
  "name": "analyze_text",
  "description": "Analyze the given text for sentiment and entities.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "text": { "type": "string" },
      "language": { "type": "string", "default": "en" }
    },
    "required": ["text"]
  },
  "source": "code"
}

From Existing MCP Servers¶

For repos that are already MCP servers:

// Original
server.tool("calculate", "Perform calculations", {
  expression: { type: "string" }
}, async ({ expression }) => {
  return eval(expression);
});

Extracted Tool:

{
  "name": "calculate",
  "description": "Perform calculations",
  "inputSchema": {
    "type": "object",
    "properties": {
      "expression": { "type": "string" }
    }
  },
  "source": "mcp"
}

Tool Naming¶

Tools follow consistent naming conventions:

Source	Convention	Example
Universal	`snake_case`	`read_file`
OpenAPI	`operationId` or `method_path`	`create_customer`
GraphQL	`type_field`	`query_user`, `mutation_create_user`
Code	Original function name	`analyze_text`

Conflict Resolution¶

When multiple tools have the same name:

Universal tools take precedence
Later sources add numeric suffix: read_file_2
Or use --exclude-tools to remove conflicts

Tool Schemas¶

All tools use JSON Schema for input validation:

Basic Types¶

{
  "type": "object",
  "properties": {
    "name": { "type": "string" },
    "count": { "type": "integer" },
    "enabled": { "type": "boolean" },
    "score": { "type": "number" }
  }
}

Arrays¶

{
  "type": "object",
  "properties": {
    "tags": {
      "type": "array",
      "items": { "type": "string" }
    }
  }
}

Nested Objects¶

{
  "type": "object",
  "properties": {
    "address": {
      "type": "object",
      "properties": {
        "street": { "type": "string" },
        "city": { "type": "string" }
      }
    }
  }
}

Enums¶

{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": ["pending", "active", "completed"]
    }
  }
}

Filtering Tools¶

Include Specific Tools¶

github-to-mcp <url> --include-tools read_file,search_code,create_customer

Exclude Tools¶

github-to-mcp <url> --exclude-tools get_readme

Skip Universal Tools¶

github-to-mcp <url> --no-universal