find-agents-md

A tool implemented as an MCP server to search for AGENTS.md and CLAUDE.md files.

Overview

This tool traverses from a specified file's directory up to the project root (where the .git directory exists) and collects the following files:

• AGENTS.md - AI agent instruction file compliant with the agents.md specification
• CLAUDE.md - Claude-specific project instruction file
• Files referenced within the above files (via markdown links)

Features

• Directory Traversal: Searches upward from the target file through parent directories
• Project Root Detection: Automatically detects project root by locating the .git directory
• Reference Resolution: Resolves markdown links [text](path) and [@project-path](path)
  • Relative paths: Resolved as relative paths from the file
  • Project root relative: Resolved from project root using [@path/to/file](...) format

Usage

As an MCP Server

Add to your Claude Desktop or other MCP client configuration file:

{
  "mcpServers": {
    "find-agents-md": {
      "command": "npx",
      "args": ["@aki77/find-agents-md"]
    }
  }
}

Using the Tool

Call the find_agents_md tool from your MCP client:

{
  "name": "find_agents_md",
  "arguments": {
    "filePath": "/path/to/your/project/src/file.ts"
  }
}

Output Format

The tool returns results in the following format:

Text format:

Found 3 file(s): 1 AGENTS.md, 1 CLAUDE.md, 1 reference

Structured data (_meta field):

{
  "files": [
    {
      "path": "/absolute/path/to/AGENTS.md",
      "type": "agents",
      "content": "..."
    },
    {
      "path": "/absolute/path/to/CLAUDE.md",
      "type": "claude",
      "content": "..."
    },
    {
      "path": "/absolute/path/to/referenced.md",
      "type": "reference",
      "content": "..."
    }
  ]
}

Development

# Build
pnpm run build

# Development mode (watch mode)
pnpm run dev

License

MIT