This server gives an AI agent read-only access to GitHub source code, letting it search, fetch, browse, and analyze Java code fragments without writing to GitHub.
Search code: search_code finds matching files/fragments with highlighted match context (requires GITHUB_TOKEN).
Read files: get_file_contents fetches a full file or a specific 1-indexed line range.
Browse repository structure: list_directory walks the repo tree, and get_repository_info/get_readme provide project metadata and overview.
List branches and commits: list_branches shows branch names with latest SHAs; list_commits shows recent history, optionally scoped to one file.
Analyze Java symbols: list_symbols enumerates classes/methods/constructors with line ranges.
Extract Java fragments: get_code_fragment extracts a named class/method/constructor body, with AST-accurate parsing via tree-sitter or a regex fallback.
Check pull request status: get_pr_status returns whether a PR is open/merged/closed, including merge time and URL.
Semantic code retrieval: find_relevant_code finds the most relevant code chunks for descriptive criteria using in-memory RAG (embeddings + BM25 fusion).
Provides read access to GitHub repositories, enabling code search, file and line-range retrieval, Java symbol and fragment extraction, directory browsing, and repository metadata, readme, branch, and commit listing.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@GitHub Code MCP show me the getReport method in ReportService.java"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP server that gives the Rapid7 SI Triage agent read access to source code
on GitHub — by default, anands-bounteous/nexpose.
It fills the gap the other two servers don't cover: jira-confluence-mcp owns
tickets/KB, log-intelligence-mcp owns log retrieval, but a Phase 2
investigation also needs to pull the actual Java source that produced a stack
trace or defect. This server hits the real GitHub REST + Search APIs directly
(no mocking, no local cloning) and is scoped specifically to reading code
and returning fragments of it, plus one narrow read-only exception —
get_pr_status — so the orchestrator can tell a support engineer whether a
past fix's pull request has actually merged. Broader issue/PR management
(creating/commenting/merging) stays out of scope.
owner/repo are optional per-call overrides on every tool, on top of the
GITHUB_OWNER/GITHUB_REPO defaults, so the server can be pointed at another
repo without a restart.
Tool | Purpose |
| The core "fetch fragments for input text" tool — GitHub code search with highlighted match fragments showing exactly where the query hit. Requires |
| Fetch a file, or just a 1-indexed inclusive line range of it. |
| Enumerate the classes/interfaces/enums/records/methods/constructors declared in a Java file, with line ranges — use this to find a symbol name for |
| Java-aware extraction of one method/class/constructor body by name. Falls back to a plain text context window if the symbol isn't a recognisable declaration. |
| Browse the repo tree. |
| Description, default branch, language, topics, stars. |
| Project overview as plain text. |
| Branch names + latest commit sha. |
| Recent history, optionally scoped to one file. |
| Live merge status of a pull request — by full PR URL (e.g. a historical-kb-mcp |
| Semantic ("RAG") retrieval: given descriptive criteria, return the specific chunk(s) of code most relevant to it — see "Semantic code retrieval (RAG)" below. |
Related MCP server: mcp-server-github
get_code_fragment/list_symbols are backed by a pluggable FRAGMENT_BACKEND:
tree-sitter (AST-accurate) — parses with tree-sitter +
tree-sitter-java. Correctly handles generics (Map<String, List<Foo>>),
annotations, records, nested/anonymous classes, and text blocks — anything a
hand-rolled brace-counter gets wrong on real Java. Optional dependency:
pip install -e ".[java]".
regex (dependency-free fallback) — matches Java declaration syntax to
find a symbol's header line, then a string/char/comment-aware balanced-brace
scanner (aware of ", ', //, /* */, and Java 15+ """ text blocks, so
a {/} inside a literal or comment can't throw off the count) finds the
matching close.
auto (default) — tries tree-sitter first; if the optional dependency
isn't installed, logs a warning and degrades to regex. Explicit choices
(tree-sitter / regex) raise instead of silently degrading.
If a requested symbol isn't a recognisable Java declaration (e.g. it's a field
name, or doesn't exist), both backends fall back to a plain
±FRAGMENT_CONTEXT_LINES text window around its first literal occurrence, with
match_type="context_window" in the response so the caller can tell it's a
lower-confidence result rather than an exact definition.
find_relevant_code answers a question neither search_code (literal/keyword
match) nor get_code_fragment (exact lookup by symbol name, which you must
already know) can: "given descriptive criteria, show me the specific code
that's relevant." It runs the same chunk → embed → hybrid-retrieve pattern
log-intelligence-mcp uses for logs, adapted to source code, entirely
in-memory per call — there's no local vector store or SI_DATA_DIR concept
here, since this is an ad-hoc per-query tool, not a persistent index.
Pipeline:
Candidate files — recursively walks the repo tree (list_directory)
and ranks files by path-token overlap with criteria, refined using Java
symbol names (list_symbols) for the top slice — deliberately not GitHub's
code-search index, which can lag indefinitely on new/small/low-star repos.
Chunking (code_chunking.py) — each candidate file's full text is
fetched and chunked. Where list_symbols recognises Java structure, leaf
symbols (methods/constructors, or a class/interface/enum/record with no
symbol nested inside its own range) become atomic chunking units, and the
lines between them (imports, package decl, class signature) become
"structural" gap units — so the file is tiled exactly once with nothing
duplicated or dropped. Non-Java files (or files where symbol extraction
fails) fall back to fixed-size line-window units. Units are greedily packed
into token-budgeted chunks (CODE_CHUNK_TARGET_TOKENS/_MAX_TOKENS), with
trailing-unit overlap between consecutive chunks (CODE_CHUNK_OVERLAP_TOKENS)
and oversized single units emitted whole and flagged rather than split.
Hybrid retrieval (code_retrieval.py) — dense embedding similarity
(EMBED_BACKEND: sentence-transformers, or the dependency-free
hashing TF-IDF fallback; auto prefers the former, degrading with a
logged warning if it isn't installed) fused with BM25 keyword matching via
Reciprocal Rank Fusion (RRF_K/DENSE_WEIGHT/SPARSE_WEIGHT), returning
the top top_k chunks with match_type="hybrid_retrieval".
Install the optional sentence-transformers backend with
pip install -e ".[rag]"; without it (or with EMBED_BACKEND=hashing
explicit), retrieval still works fully offline via the hashing fallback.
Copy .env.example to .env:
GITHUB_TOKEN=<create at github.com/settings/tokens>
GITHUB_API_BASE_URL=https://api.github.com
GITHUB_OWNER=anands-bounteous
GITHUB_REPO=nexpose
GITHUB_DEFAULT_REF=
MAX_FILE_KB=500
FRAGMENT_CONTEXT_LINES=20
FRAGMENT_BACKEND=auto
HTTP_TIMEOUT=30
HTTP_MAX_RETRIES=4
MCP_HTTP_HOST=127.0.0.1
MCP_HTTP_PORT=8082
# find_relevant_code (RAG) — chunking
CODE_CHUNK_TARGET_TOKENS=400
CODE_CHUNK_MAX_TOKENS=800
CODE_CHUNK_OVERLAP_TOKENS=80
# find_relevant_code (RAG) — embeddings: auto | sentence-transformers | hashing
EMBED_BACKEND=auto
EMBED_MODEL=all-mpnet-base-v2
EMBED_DIM_FALLBACK=512
# find_relevant_code (RAG) — hybrid retrieval (RRF)
RRF_K=60
DENSE_WEIGHT=1.0
SPARSE_WEIGHT=1.0
CANDIDATE_POOL=30GITHUB_TOKEN is a GitHub personal access token
(github.com/settings/tokens). It's optional for reading public repos — but
required for search_code (GitHub's code search API rejects unauthenticated
requests outright) and strongly recommended for everything else (5,000
requests/hour authenticated vs. 60/hour anonymous). A fine-grained PAT with
read-only "Contents" access is enough; no repo write scope is needed since
this server never writes to GitHub.
GITHUB_API_BASE_URL is overridable for GitHub Enterprise Server. It's
normalised to just the scheme+host, same as any pasted API URL.
The HTTP client retries 429/5xx with exponential backoff (honouring
Retry-After), and additionally watches GitHub's primary rate-limit signal
(X-RateLimit-Remaining: 0 + X-RateLimit-Reset) to sleep until the limit
resets rather than blindly backing off — controlled by HTTP_MAX_RETRIES and
HTTP_TIMEOUT.
cd github-mcp
python -m venv .venv && source .venv/bin/activate # .venv\Scripts\Activate.ps1 on Windows
pip install -e . # base install: mcp, httpx, uvicorn, numpy
pip install -e ".[java]" # + tree-sitter/tree-sitter-java for AST-accurate fragments
pip install -e ".[rag]" # + sentence-transformers for the find_relevant_code embedding backend
cp .env.example .env # fill in GITHUB_TOKEN
# stdio:
python -m github_mcp --transport stdio
# HTTP (streamable-http at http://127.0.0.1:8082/mcp):
python -m github_mcp --transport http{
"mcpServers": {
"github": {
"command": "python",
"args": ["-m", "github_mcp", "--transport", "stdio"],
"env": {
"GITHUB_TOKEN": "…",
"GITHUB_OWNER": "anands-bounteous",
"GITHUB_REPO": "nexpose"
}
}
}
}This server's HTTP transport defaults to 8082 — jira-confluence-mcp uses
8080 and log-intelligence-mcp uses 8081, so all three can run simultaneously.
pytest # in an environment with pytest installed
python tests/_runner.py # offline harness when pytest isn't installedCovers base-URL normalisation, content decoding, line-slicing, directory/repo/
branch/commit normalisation, search-query building and result normalisation,
and — via a stub HTTP transport (FakeClient, no network needed) — file
fetch with the MAX_FILE_KB size guard, directory listing, repo info/readme/
branches/commits, the search_code no-token guard, and the fragment-backend
factory. The Java regex backend is exercised directly against a realistic
fixture source file (tests/fixtures/Sample.java) covering nested classes, an
interface, a generic method, an annotated method, and a string literal
containing {/} to prove brace-in-string masking works.
The find_relevant_code RAG pipeline has its own coverage: symbol-aware
chunking correctness (test_code_chunking.py — no duplication/gaps, oversized-
unit flagging, line-window fallback), the hashing embedding backend + BM25
tokenisation + RRF fusion against a hand-computed score
(test_embeddings_bm25.py), and end-to-end tool behaviour via the FakeClient
pattern (test_find_relevant_code.py — candidate-file discovery via the
list_directory/list_symbols tree walk, and hybrid-retrieval results). These
force EMBED_BACKEND=hashing explicitly, so they never need
sentence-transformers installed.
42 tests total, all offline — none need GITHUB_TOKEN, network access, or the
optional sentence-transformers/tree-sitter-java dependencies.
If
tree-sitter-javaisn't installed, tests targetRegexJavaBackendexplicitly rather than relying onFRAGMENT_BACKEND=autoresolution, so the suite stays runnable regardless of what's pip-installed.
Live GitHub API calls (a real
search_code/get_file_contentsagainstanands-bounteous/nexpose) need a realGITHUB_TOKENand network access, which the automated test suite doesn't exercise — see "Install & run" above to try them manually.
Extract one named class/method/constructor body from a Java file.
Uses AST-accurate parsing when tree-sitter-java is installed, else a regex-based heuristic; falls back to a plain text-context window (match_type="context_window") if the symbol isn't a recognisable Java declaration.
| Name | Required | Description | Default |
|---|---|---|---|
| ref | No | ||
| path | Yes | ||
| repo | No | ||
| owner | No | ||
| symbol | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the AST-based vs regex-based vs context-window fallback behavior, which is valuable beyond what annotations (none) provide. However, it references a match_type parameter that is not present in the input schema, creating confusion. With no annotations, it also omits return format and error behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the purpose, and the second sentence provides technical detail without excessive length. However, the second sentence is dense and the unexpected match_type reference muddies clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 5 parameters and no output schema, yet the description covers only the basic extraction mode and leaves repo/owner/ref semantics, return type, and failure behavior undefined. Standalone, an agent would struggle to invoke this correctly for remote repositories.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaning for path and symbol (the Java file and the named declaration), but repo, owner, and ref are not explained. Since schema description coverage is 0%, the description must compensate, but it does so inadequately for 3 of the 5 parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it extracts one named class/method/constructor body from a Java file, which is a specific verb+resource. This distinguishes it from siblings like search_code (searching), get_file_contents (whole file), and list_symbols (listing symbols).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you need a specific named declaration body, but it does not explicitly state when to use this tool over siblings like search_code or get_file_contents. It lacks alternatives or exclusions, so only the basic context is implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch a file's contents, or a 1-indexed inclusive line range of it.
| Name | Required | Description | Default |
|---|---|---|---|
| ref | No | ||
| path | Yes | ||
| repo | No | ||
| owner | No | ||
| end_line | No | ||
| start_line | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the line-range indexing and inclusiveness behavior, which is helpful. However, with no annotations available, it does not cover other important behaviors such as read-only nature, error cases, or how repository context is resolved via parameters.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, focused sentence conveys the core functionality without any redundant words or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With six parameters, no output schema, and no annotations, the one-line description is insufficient to fully understand how to invoke the tool correctly, especially regarding repository identification and line range parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description only indirectly references line ranges without explicitly mapping to start_line/end_line or explaining path, repo, owner, and ref. It does not compensate for the missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the action (fetch) and resource (file contents), with a specific nuance about 1-indexed inclusive line ranges. However, it does not explicitly differentiate from the sibling get_code_fragment, which may also fetch file content or ranges.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool compared to alternatives like get_code_fragment or search_code. The context is implied but not stated, and there are no exclusions or prerequisite conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch the repository's README as plain text.
| Name | Required | Description | Default |
|---|---|---|---|
| ref | No | ||
| repo | No | ||
| owner | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the full burden of behavioral disclosure. It mentions the output format ('as plain text') and implicitly communicates a read-only operation, but lacks details on default branch behavior, error handling, or response structure. This is basic but non-contradictory information.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. It efficiently conveys the core purpose and output format.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
As a simple read tool, the description is minimally viable but misses important context such as parameter semantics and behavior when ref is omitted or no README exists. With no annotations or output schema, the description could be more helpful, but it is not severely lacking.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain the meaning of the three parameters (owner, repo, ref). While the purpose helps infer repository identity, the description provides no explicit guidance on how to construct parameters, leaving significant ambiguity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function with a specific verb and resource: 'Fetch the repository's README as plain text.' This distinctly differentiates it from sibling tools like get_file_contents (generic file retrieval) and search_code.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this tool is for retrieving the README file, but it does not explicitly state when to use it over alternatives like get_file_contents. There are no exclusions or alternative guidance provided, leaving usage context implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch repository metadata: description, default branch, language, topics.
| Name | Required | Description | Default |
|---|---|---|---|
| repo | No | ||
| owner | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must disclose behavioral context. It only states that metadata is fetched, implying a read operation, but doesn't mention whether authentication is required, how optional parameters behave, or any side effects (e.g., rate limits). This is a thin disclosure for a tool with no annotation support.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the action and enumerates the returned fields. Every word contributes value, with no redundant phrasing or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple, but the description lacks essential context: it doesn't clarify the optional parameter relationship (e.g., whether both owner and repo are needed), what happens if both are null, or the exact return structure. Since there is no output schema, the description should provide more detail about the response, which it only partially does by listing fields.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description entirely omits the 'repo' and 'owner' parameters. It adds no meaning beyond the property names themselves, which are self-explanatory but could benefit from clarifying how they combine (e.g., 'owner/repo' vs separate). The description fails to compensate for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Fetch') and clearly identifies the resource ('repository metadata') with a list of concrete fields (description, default branch, language, topics). It distinguishes from siblings like get_readme and list_branches, though it doesn't explicitly state those exclusions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when repository metadata is needed but provides no explicit guidance on when to use this tool versus alternatives like get_readme or list_branches. There are no when/not-to-use conditions or prerequisite context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List branches with their latest commit sha.
| Name | Required | Description | Default |
|---|---|---|---|
| repo | No | ||
| owner | No | ||
| max_results | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses that the output includes the latest commit sha, which is a useful output trait, and the verb 'list' implies a read-only operation. However, it does not mention pagination, the effect of max_results, or any authentication requirements, so more context would improve transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, direct sentence that clearly states the tool's purpose without redundancy. It could add a sentence about parameters without becoming verbose, but as written it is efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is minimal for a tool with 3 undocumented parameters and no annotations. It does not explain how parameters interact, what the output structure looks like beyond the SHA, or how it differs from list_commits. This is insufficient for an agent to confidently invoke the tool with correct arguments.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description adds no explanation for the three parameters (repo, owner, max_results). It does not clarify that repo/owner identify the repository or that max_results limits the number of returned branches. The description fails to compensate for the missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'List' and identifies the resource 'branches' while adding the detail 'with their latest commit sha'. This clearly distinguishes it from siblings like list_commits (which lists commit history) and list_directory (which lists files).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention when to prefer list_branches over list_commits or get_repository_info, nor any exclusions or context for decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List recent commits, optionally scoped to a single file path.
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | ||
| repo | No | ||
| owner | No | ||
| max_results | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It implies a read-only operation via 'list' but does not state return format, ordering, pagination, authentication requirements, or failure behavior. This is a significant gap for a tool with no annotation support.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no fluff, front-loading the main action. It earns a high score for brevity, though the brevity sacrifices detail elsewhere.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 4 optional parameters, no output schema, and no annotations, this one-sentence description is insufficient. It does not clarify the data source (repo/owner) or result limits, making it incomplete for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description only hints at the 'path' parameter ('optionally scoped to a single file path') and ignores 'repo', 'owner', and 'max_results'. With 0% schema description coverage, three of four parameters remain semantically unexplained, leaving the agent to guess their meanings.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and resource ('commits'), and adds a scoping condition ('optionally scoped to a single file path') that differentiates it from sibling tools like list_branches or get_file_contents. This makes the purpose immediately clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It clearly indicates when to use the tool: to see recent commits, optionally filtered by a file path. This provides enough context for a simple read operation, though it does not explicitly name alternatives or exclusions, stopping short of full guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the files and subdirectories at a path in the repo (default: repo root).
| Name | Required | Description | Default |
|---|---|---|---|
| ref | No | ||
| path | No | ||
| repo | No | ||
| owner | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavior. It only states the basic listing action and default path but omits details such as whether the listing is recursive, what entry types are included, whether hidden files are shown, and the structure of the returned data. This is a significant gap for a tool with no output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no extraneous words. It clearly states the action, resource, and default location in an efficient manner.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given there are 4 parameters, no output schema, and no annotations, the description is incomplete. It does not explain the return value, parameter semantics, or any behavioral caveats, leaving the agent without crucial information for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has a 0% description coverage and the description does not explain the 'ref', 'owner', or 'repo' parameters. It only tangentially mentions 'path' and 'repo root', leaving the agent to guess the meaning and relationships of the other parameters. Since coverage is low, the description should compensate but does not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('list') and resource ('files and subdirectories at a path in the repo'), clearly distinguishing it from sibling tools like get_file_contents or search_code. It also mentions the default behavior (repo root), adding useful scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use it (when you need to list directory contents) but provides no explicit guidance on when not to use it or how it compares to alternatives like search_code or get_file_contents. There is no mention of prerequisites or context where another tool would be more appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the classes/interfaces/enums/records/methods/constructors declared in a Java file, with their line ranges — use this to find a symbol name to pass to get_code_fragment.
| Name | Required | Description | Default |
|---|---|---|---|
| ref | No | ||
| path | Yes | ||
| repo | No | ||
| owner | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the output type (line ranges for declared symbols) and scopes the tool to Java files, but it does not explain behavior for non-Java files, handling of repo refs, or error conditions. This is acceptable but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single well-structured sentence that front-loads the core capability and then attaches the use case. Every word contributes value, with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple listing tool, the description covers what it returns and why to use it, but omits parameter context (especially repo/owner/ref) and any output format beyond 'line ranges.' Without annotations or an output schema, this leaves some ambiguity for invocation in a repository context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain the meaning of path, repo, owner, or ref. The only implicit hint is 'Java file,' but none of the four parameters are semantically clarified, so the agent must infer their roles from names alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and resource ('symbols') while enumerating the exact symbol types and including 'line ranges,' making the tool's function precise. It also distinguishes itself from sibling tools like get_file_contents by positioning itself as a symbol-finder for get_code_fragment.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states 'use this to find a symbol name to pass to get_code_fragment,' giving clear contextual purpose and a downstream alternative. It does not explicitly state when not to use it, but the forward reference to get_code_fragment provides sufficient usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search code in the repo for a query string; returns matching files with highlighted fragments showing exactly where the match occurs. Requires GITHUB_TOKEN.
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | ||
| repo | No | ||
| owner | No | ||
| query | Yes | ||
| extension | No | ||
| max_results | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavior itself. It mentions an auth requirement (GITHUB_TOKEN) and describes the return format (matching files with highlighted fragments). However, it omits details like whether repo/owner are required, whether the search is read-only, pagination behavior, or any rate limits, so it only partially covers behavioral transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the primary purpose, and adds relevant details (highlighted fragments, auth token) without unnecessary verbiage. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 6 parameters, no annotations, and no output schema, yet the description only covers the query string and return format. It does not clarify how to scope the search (owner/repo/path), the behavior of max_results, or the meaning of extension. This leaves significant gaps for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage and 6 parameters, but the description only clarifies 'query string' and mentions 'repo' indirectly. It doesn't explain owner, path, extension, or max_results, leaving the agent to infer their meaning from the parameter names alone. This is insufficient compensation for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Search code in the repo') and identifies the primary resource ('code') and what it returns (matching files with highlighted fragments). It clearly distinguishes this from sibling tools like get_file_contents (which retrieves file contents) and list_symbols (which lists symbols).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage (when you need to find code matching a query) but does not explicitly discuss alternatives or provide when-not-to-use guidance. It gives clear context for its core function but no exclusions or comparisons to sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v1.0.0get_code_fragmentget_file_contentsget_readmeget_repository_infolist_brancheslist_commitslist_directorylist_symbolssearch_codeEach tool targets a distinct resource and action: search_code queries, get_file_contents retrieves file content, list_symbols lists declarations, get_code_fragment extracts a symbol body, list_directory navigates, get_repository_info and get_readme provide different repo overview types, and list_branches/list_commits cover history. The related pairs (list_symbols/get_code_fragment, get_repository_info/get_readme) are clearly complementary with no functional overlap.
All tool names follow the same snake_case verb_noun pattern with a predictable verb choice: get_* for fetching single items, list_* for enumerating collections, and search_code for querying. This consistent structure makes the tool set easy to navigate.
Nine tools is well within the ideal 3-15 range for a focused code exploration server. Each tool has a clear purpose and collectively they cover the core aspects of reading and navigating a repository without redundancy.
The surface covers search, file contents, symbol extraction, directory listing, repo metadata, README, branches, and commits. Minor gaps exist, such as no direct diff viewing or fetching a file at a specific commit, but these are not critical blockers for typical code navigation workflows.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Access the GitHub API, enabling file operations, repository management, search functionality, and…
Code intelligence for LLMs. Analyze, search, and retrieve code from any public git repository.
Screens public GitHub repos and PRs to generate risk maps, findings, and merge-readiness signals.
Ask a codebase what calls what: search, blast radius, paths between symbols, and diffs.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/hareeshbounteous/github-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
