Skip to main content
Glama
jbouder

agent-docs-mcp

by jbouder
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Remote

Agent Docs MCP

MCP Server that provides coding agents with automatic access to AGENTS.md documentation from GitHub repositories. This enables AI assistants to understand your codebase conventions, patterns, and guidelines without manual intervention.

Why Use This?

When working with AI coding agents, they often need context about:

  • Your coding standards and conventions

  • Architecture decisions and patterns

  • API usage and best practices

  • Project-specific guidelines

This MCP server makes that documentation automatically available to agents, so they can:

  • Automatically reference your coding guidelines when making changes

  • Search for specific patterns or implementations

  • Understand context before implementing features

  • Follow conventions without being explicitly told

Related MCP server: GitHub MCP Server

Getting Started

Add the following to your MCP configuration to connect your AI assistant to the documentation:

Configuration

{
  "servers": {
    "agent-docs-mcp": {
      "command": "npx",
      "args": ["@jbouder/agent-docs-mcp"],
      "env": {
        "REPO_URLS": "[\"https://github.com/jbouder/acolyte\",\"https://github.com/metrostar/comet\"]"
      }
    }
  }
}

This will automatically make AGENTS.md files available from:

  • https://github.com/jbouder/acolyte/blob/main/AGENTS.md

  • https://github.com/MetroStar/comet/blob/main/AGENTS.md

Environment Variables:

  • REPO_URLS: JSON array of GitHub repository URLs

    • The server automatically adds /blob/main if not specified

    • You can specify branches: https://github.com/owner/repo/blob/develop

    • You can specify subdirectories: https://github.com/owner/repo/blob/main/docs

How It Works

Resources (Automatic)

The documentation is exposed as MCP resources, which means agents can automatically access it when working on your code. No manual tool calls needed!

Tools (On-Demand)

Tool

When Agents Use It

read_agent_docs

To read coding guidelines, patterns, and conventions before implementing features

search_agent_docs

To find specific information about APIs, patterns, or implementation details

Agents will automatically use these tools when:

  • Starting work on a new feature

  • Fixing bugs and needing context

  • Implementing APIs or following patterns

  • Understanding architecture decisions

Supported URL Formats

The server intelligently handles various GitHub URL formats:

  • https://github.com/owner/repo → auto-adds /blob/main/AGENTS.md

  • https://github.com/owner/repo/blob/branch → adds /AGENTS.md

  • https://github.com/owner/repo/blob/branch/path → adds /AGENTS.md

  • https://github.com/owner/repo/tree/branch → converts to blob and adds /AGENTS.md

All URLs are automatically converted to raw content URLs for fetching.

Creating AGENTS.md

Create an AGENTS.md file in your repository with coding guidelines, patterns, and context. Example:

# Agent Guidelines for MyProject

## Architecture

- We use a microservices architecture
- API Gateway pattern for routing
- Event-driven communication between services

## Coding Standards

- TypeScript with strict mode enabled
- ESLint configuration in .eslintrc.json
- Jest for testing with >80% coverage requirement

## API Patterns

- All endpoints use RESTful conventions
- Authentication via JWT tokens
- Rate limiting: 100 requests per minute

## Common Tasks

### Adding a New API Endpoint

1. Create route in `src/routes/`
2. Add controller in `src/controllers/`
3. Write tests in `__tests__/`
4. Update OpenAPI spec

### Database Migrations

Use `npm run migrate` to run migrations...

Example Agent Interactions

With this MCP server configured, agents can:

Automatic Context:

Agent: "I need to implement a new API endpoint for user profiles"
[Agent automatically reads documentation]
Agent: "Based on the guidelines, I'll create the route in src/routes/,
       add a controller, write tests, and update the OpenAPI spec..."

Searching for Patterns:

You: "Add authentication to the new endpoint"
Agent: [Searches docs for "authentication"]
Agent: "I found the JWT authentication pattern. I'll use the existing
       middleware from src/middleware/auth.ts..."

Running Locally

The MCP server is built using the official TypeScript MCP SDK and follows the existing project structure and patterns.

Build the Server

npm run build

Configuring MCP Client for your server

{
  "mcpServers": {
    "agent-docs-mcp": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/YOUR/PROJECT/agent-docs-mcp/dist/index.js"],
      "env": {
        "REPO_URLS": "[\"https://github.com/jbouder/acolyte\"]"
      }
    }
  }
}

Available Tools

2 tools
read_agent_docsA

Read agent documentation and coding guidelines from configured repositories. Use this when you need context about how to work with a codebase, understand coding patterns, architecture decisions, or get implementation guidelines. The documentation provides best practices, conventions, and important context for making code changes.

ParametersJSON Schema
NameRequiredDescriptionDefault
repositoryNoOptional: specific repository URL or name to get docs from. If not provided, returns all configured docs.

TDQS

A3.6/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. The verb 'Read' implies a non-mutating operation, and the description clarifies the source ('configured repositories') and the kind of content returned. It does not disclose output format, potential size limits, or failure modes, but for a simple read tool this is acceptable.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is reasonably concise, with the core purpose front-loaded in the first sentence. The third sentence is somewhat redundant with the first, but it does reinforce the practical value of the documentation without excessive bloat.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with one optional parameter and no output schema, the description covers when and why to use it, what it reads, and the source scope. It does not explain return format, but the tool's purpose is simple and the schema fully specifies the only input.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, and the single optional parameter is already well documented ('specific repository URL or name' and default behavior). The description adds no additional parameter detail, but none is needed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Read') and resource ('agent documentation and coding guidelines from configured repositories'). It is clear what the tool does, though it does not explicitly contrast with the sibling search_agent_docs, so differentiation is left mostly to the name.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit 'Use this when' guidance covering codebase context, coding patterns, architecture decisions, and implementation guidelines. It does not mention when to prefer search_agent_docs instead, but the usage context is clear enough for an agent.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_agent_docsA

Search through agent documentation for specific information about coding patterns, architecture, APIs, or implementation details. Use this when you need to find specific guidance before implementing a feature or fixing a bug.

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYesWhat to search for in the documentation (e.g., 'authentication pattern', 'error handling', 'API endpoints')

TDQS

A3.8/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full disclosure burden. The verb 'search' implies a read-only operation, and the description says what it searches, but it does not disclose what the response looks like (snippets, ranked matches, full sections), result limits, or how matches are ordered. Adequate but minimal behavioral context beyond the verb itself.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences, zero filler. The first sentence front-loads the action and resource, the second carries the usage trigger. Every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter search tool with no output schema, this is nearly complete: it defines the domain, what to search for, and when to use it. The only gap is the response format, which an agent would benefit from knowing to set expectations, but the tool's simplicity keeps the omission minor.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The tool description adds only marginal value by repeating the same topical scope (coding patterns, architecture, APIs) that the schema's query example already conveys. It does not add syntax, format, or query-construction guidance beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'Search through agent documentation for specific information about coding patterns, architecture, APIs, or implementation details.' The scope is clearly defined and the action ('search') is distinguishable from the sibling 'read_agent_docs', but the description never explicitly names the sibling or states the boundary, so it misses full differentiation credit.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit trigger: 'Use this when you need to find specific guidance before implementing a feature or fixing a bug.' This tells an agent when to invoke the tool but does not state when NOT to use it or mention read_agent_docs as the alternative for reading whole documents, so exclusion guidance is absent.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 2 tool updatesv1.0.0
    • First observedread_agent_docs
    • First observedsearch_agent_docs
Deploy Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.8/5.0

Scored across 2 tools

Disambiguation4/5

read_agent_docs and search_agent_docs are clearly differentiated by mode: one retrieves full documentation/context, the other finds specific guidance. There is some conceptual overlap since both access the same docs, but descriptions make the boundary clear.

Naming Consistency5/5

Both tools follow the same verb_noun pattern: read_agent_docs and search_agent_docs. The naming is consistent, predictable, and clearly indicates what each tool does.

Tool Count3/5

With only two tools, the server feels minimal, but the scope is narrowly focused on documentation access. This falls into the borderline range where 1-2 tools feels thin, though it is not unreasonable for a docs-only server.

Completeness4/5

Read and search cover the main documentation-retrieval workflows with no obvious dead ends. A list/discovery tool could be a minor enhancement, but it is not strictly necessary since search can locate relevant docs.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers