CodeScribe MCP Server Documentation¶

Overview¶

The CodeScribe MCP (Model Context Protocol) server enables AI assistants like Claude Code to interact with codebases, generate documentation, and perform security analysis through natural language commands.

Quick Start¶

Configuration¶

Add to your .mcp.json:

{
  "mcpServers": {
    "codescribe": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--network", "traefik_proxy",
        "--volume", "/srv/dockerdata:/data/dockerdata:ro",
        "--volume", "/home:/data/home:ro",
        "codescribe:latest",
        "node", "src/mcp/server.js"
      ]
    }
  }
}

Restart Claude Code¶

After updating .mcp.json, restart Claude Code to load the MCP server.

Verify Installation¶

# Test MCP tools listing
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | \
docker run --rm -i \
    -v /srv/dockerdata:/data/dockerdata:ro \
    codescribe:latest \
    node src/mcp/server.js

Tools Reference¶

scan_directory¶

Scan a directory and return its structure with all files and folders.

Parameters:

Parameter	Type	Required	Description
`path`	string	Yes	Absolute path to the directory to scan
`ignorePatterns`	string[]	No	Additional patterns to ignore
`maxDepth`	number	No	Maximum directory depth (default: 20)

Example Usage:

User: "Scan the n8n service directory"
Claude: [Uses scan_directory with path="/data/dockerdata/n8n-compose"]

Response:

{
  "success": true,
  "totalFiles": 15,
  "structure": {
    "name": "n8n-compose",
    "type": "directory",
    "children": [...]
  },
  "filePaths": [
    "/data/dockerdata/n8n-compose/docker-compose.yml",
    "/data/dockerdata/n8n-compose/.env",
    ...
  ]
}

generate_documentation¶

Generate markdown documentation from a directory or list of files.

Parameters:

Parameter	Type	Required	Default	Description
`rootDir`	string	Yes	-	Root directory path
`filePaths`	string[]	No	All files	Specific files to include
`ignorePatterns`	string[]	No	[]	Patterns to ignore
`includeTreeView`	boolean	No	true	Include directory tree
`securityCheck`	boolean	No	true	Filter files with secrets
`aiOptimized`	boolean	No	false	Optimize for AI consumption

Example Usage:

User: "Generate documentation for the monitoring stack"
Claude: [Uses generate_documentation with rootDir="/data/dockerdata/monitoring", aiOptimized=true]

Response:

Returns markdown documentation with: - File tree structure - Syntax-highlighted file contents - Statistics (file count, character count, token count) - Security filtering summary (if applicable)

process_remote_repository¶

Clone and document a remote Git repository.

Parameters:

Parameter	Type	Required	Default	Description
`url`	string	Yes	-	Repository URL or shorthand (e.g., "owner/repo")
`branch`	string	No	Default branch	Specific branch to clone
`securityCheck`	boolean	No	true	Filter files with secrets
`ignorePatterns`	string[]	No	[]	Additional patterns to ignore

Supported URL Formats:

Full URL: https://github.com/owner/repo
GitHub shorthand: owner/repo
GitLab URL: https://gitlab.com/owner/repo
Bitbucket URL: https://bitbucket.org/owner/repo
SSH URL: [email protected]:owner/repo.git

Example Usage:

User: "Document the anthropics/claude-code repository"
Claude: [Uses process_remote_repository with url="anthropics/claude-code"]

Response:

Returns markdown documentation with: - Repository metadata - Full source documentation - Token count statistics - Security scan results

security_scan¶

Scan files for security issues like hardcoded secrets.

Parameters:

Parameter	Type	Required	Default	Description
`rootDir`	string	Yes	-	Root directory to scan
`filePaths`	string[]	No	All files	Specific files to scan
`generateReport`	boolean	No	false	Generate markdown report

Detected Patterns:

Type	Examples
AWS Keys	`AKIA...`, AWS secret access keys
GitHub Tokens	`ghp_`, `gho_`, `github_pat_`
Anthropic Keys	`sk-ant-api...`
OpenAI Keys	`sk-...` (48 chars)
Private Keys	RSA, DSA, EC, PGP private keys
Generic Secrets	Password assignments, high-entropy strings

Example Usage:

User: "Run a security scan on the authentication service"
Claude: [Uses security_scan with rootDir="/data/dockerdata/authentik", generateReport=true]

Response:

{
  "success": true,
  "totalFiles": 42,
  "filesWithFindings": 3,
  "totalFindings": 5,
  "bySeverity": {
    "critical": 0,
    "high": 2,
    "medium": 2,
    "low": 1
  },
  "findings": [...]
}

count_tokens¶

Count tokens for various AI models.

Parameters:

Parameter	Type	Required	Default	Description
`text`	string	Yes	-	Text to count tokens for
`estimateCosts`	boolean	No	false	Include cost estimates

Supported Models:

Model	Encoding	Notes
GPT-4o	o200k_base	Latest OpenAI encoding
GPT-4	cl100k_base	Standard OpenAI encoding
Claude 3.5 Sonnet	estimate	~1.1x GPT-4 tokens

Example Usage:

User: "How many tokens is this documentation?"
Claude: [Uses count_tokens with the documentation text, estimateCosts=true]

Response:

{
  "success": true,
  "characters": 15234,
  "words": 2847,
  "lines": 342,
  "tokens": {
    "gpt-4o": 3521,
    "gpt-4": 3842,
    "claude-3.5-sonnet": 4226
  },
  "costs": {
    "gpt-4o": "$0.0088",
    "claude-3.5-sonnet": "$0.0127"
  }
}

get_repository_info¶

Get information about a remote repository without cloning.

Parameters:

Parameter	Type	Required	Description
`url`	string	Yes	Repository URL or shorthand

Example Usage:

User: "What's in the n8n-io/n8n repository?"
Claude: [Uses get_repository_info with url="n8n-io/n8n"]

Response:

{
  "owner": "n8n-io",
  "repo": "n8n",
  "description": "Fair-code licensed workflow automation tool...",
  "stars": 35000,
  "forks": 4200,
  "language": "TypeScript",
  "defaultBranch": "master",
  "topics": ["automation", "workflow", "nodejs"]
}

Resources¶

Default Ignore Patterns¶

URI: codescribe://config/ignore-patterns

Returns the list of file patterns ignored by default during scanning:

[
  "node_modules",
  ".git",
  "__pycache__",
  "*.pyc",
  "dist",
  "build",
  "*.min.js",
  "*.map",
  "coverage",
  ".env*",
  "*.lock",
  "package-lock.json"
]

Usage Patterns¶

Documenting a Service¶

User: "Generate documentation for the Traefik service for my context"
Claude: Let me generate documentation for the Traefik configuration.

[Uses generate_documentation with:
  - rootDir: "/data/dockerdata/traefik"
  - aiOptimized: true
  - securityCheck: true]

Here's the documentation for the Traefik service:
[Generated markdown with tree structure, configs, and stats]

Security Audit¶

User: "Check the new authentication service for leaked secrets"
Claude: I'll run a security scan on the authentication service.

[Uses security_scan with:
  - rootDir: "/data/dockerdata/auth-service"
  - generateReport: true]

Security scan results:
- 2 high-severity findings in config files
- 1 medium finding in test data
[Full report with recommendations]

Analyzing External Repository¶

User: "I want to understand how the fastapi library works"
Claude: Let me fetch and analyze the FastAPI repository.

[Uses get_repository_info with url="tiangolo/fastapi"]
[Uses process_remote_repository with url="tiangolo/fastapi"]

FastAPI is a modern web framework with:
[Summary based on generated documentation]
Token count: ~150,000 tokens - too large for single context
[Suggests focusing on specific directories]

Estimating Context Usage¶

User: "How much context would documenting our entire infrastructure take?"
Claude: Let me scan and estimate the token count.

[Uses scan_directory with path="/data/dockerdata"]
[Uses count_tokens on representative sample, estimateCosts=true]

Infrastructure documentation would be approximately:
- Total files: 2,847
- Estimated tokens: ~500,000 GPT-4o tokens
- Estimated cost: $1.25 per full context load
[Recommends selective documentation]

Error Handling¶

All tools return errors in a consistent format:

{
  "success": false,
  "error": "Directory not found: /invalid/path"
}

Common errors:

Error	Cause	Solution
"Directory not found"	Invalid path	Check path exists in container
"Permission denied"	Read access	Ensure path is mounted in container
"Repository not found"	Invalid URL	Verify repository exists and is public
"Clone failed"	Network/auth	Check network connectivity

Best Practices¶

Start with scan_directory: Before generating documentation, scan to understand the structure
Use aiOptimized for LLM context: The AI-optimized output is designed specifically for Claude's context window
Enable security scanning: Always keep securityCheck: true (default) when documenting codebases
Check token counts: Use count_tokens to ensure documentation fits within context limits
Filter large repositories: For large repos, specify filePaths or use ignorePatterns to focus on relevant code
Use shorthand URLs: For GitHub, use owner/repo instead of full URLs for convenience

Technical Implementation¶

Runtime: Node.js 20 with ES modules
MCP SDK: @modelcontextprotocol/sdk v1.0
Transport: stdio (stdin/stdout)
Token Counting: js-tiktoken with official OpenAI BPE encodings

Troubleshooting¶

MCP Server Not Loading¶

Check Docker can run the container:

docker run --rm codescribe:latest node --version

Verify .mcp.json syntax is valid JSON
Restart Claude Code completely

Paths Not Found¶

Remember paths inside the container are mapped: - /srv/dockerdata → /data/dockerdata - /home → /data/home

Use the container paths when calling tools.

Large Repository Timeouts¶

For repositories over 100MB: 1. Use ignorePatterns to exclude unnecessary files 2. Specify branch to avoid fetching all branches 3. Consider cloning manually and using generate_documentation instead