Troubleshooting

Troubleshooting

Common issues and solutions for fedramp-docs-mcp.

Installation Issues

npm install fails with EACCES

mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
npm install -g fedramp-docs-mcp

npx command not found

Ensure Node.js is properly installed:

node --version  # Should be 18+
npm --version   # Should be 9+

Runtime Issues

First run is slow

Expected. The server clones FedRAMP/docs (~50MB) on first run. Subsequent runs use the cache.

health_check returns 0 files

Repository clone may have failed. Delete cache and retry:

rm -rf ~/.cache/fedramp-docs
npx fedramp-docs-mcp

Git clone fails

Check network connectivity:

curl -I https://github.com

Behind a proxy? Configure git:

git config --global http.proxy http://proxy:8080

Out of memory

Increase Node.js memory:

NODE_OPTIONS="--max-old-space-size=4096" npx fedramp-docs-mcp

MCP Client Issues

Server not appearing in Claude Desktop

1. Check config file location:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json

2. Validate JSON syntax:

   cat ~/Library/Application\ Support/Claude/claude_desktop_config.json | jq .

3. Restart Claude Desktop completely

Connection timeout

Test the server directly:

echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | npx fedramp-docs-mcp

Docker Issues

Container exits immediately

MCP uses stdio. Run with -it:

docker run -it fedramp-docs-mcp

Permission denied on volume

docker run -it --user $(id -u):$(id -g) fedramp-docs-mcp

Debug Mode

Enable verbose logging:

DEBUG=* npx fedramp-docs-mcp

Getting Help

1. Check GitHub Issues
2. Open a new issue with:
   • Node.js version
   • Operating system
   • Error message
   • Steps to reproduce