This guide explains how to install and use Tech Debt MCP from GitHub Packages.
GitHub Packages is a package hosting service that lets you host your code packages privately or publicly. Tech Debt MCP is primarily published to npm (the recommended install method). GitHub Packages is available as an alternative for corporate environments or private registry setups.
The package is published to both npm and GitHub Packages. The easiest way is to install from npm:
npm install -g tech-debt-mcpIf you prefer to use GitHub Packages, you need to authenticate first.
- Go to GitHub Settings > Developer settings > Personal access tokens > Tokens (classic)
- Click "Generate new token (classic)"
- Select scopes:
- ✅
read:packages- to download packages - ✅
write:packages- if you plan to publish
- ✅
- Generate and copy the token
Create or update ~/.npmrc in your home directory:
@PierreJanineh:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKENReplace YOUR_GITHUB_TOKEN with your actual token from Step 1.
Important: Never commit this file to version control! Add to .gitignore if needed.
npm install -g @PierreJanineh/tech-debt-mcpOr for local project installation:
npm install @PierreJanineh/tech-debt-mcpAfter installation, you can use the MCP server in two ways:
tech-debt-mcpThis starts the MCP server on stdio, ready to communicate with GitHub Copilot or other MCP clients.
Tech Debt MCP is an MCP server — it communicates over stdio with MCP-compatible clients (Claude Code, GitHub Copilot, etc.). It is not imported as a library.
To use Tech Debt MCP with an MCP-compatible client:
-
Install the package (using either method above)
-
Configure in your MCP settings:
Add to your MCP configuration file (usually ~/.config/cline/cline_mcp_settings.json or similar):
{
"mcpServers": {
"tech-debt": {
"command": "tech-debt-mcp",
"args": []
}
}
}- Or if installed locally in your project:
{
"mcpServers": {
"tech-debt": {
"command": "node",
"args": ["./node_modules/.bin/tech-debt-mcp"]
}
}
}npm ERR! 404 Not Found - GET https://registry.npmjs.org/@PierreJanineh/tech-debt-mcp
This means you're trying to install from npm registry but the scoped package is on GitHub Packages. Either:
- Use the non-scoped version:
npm install -g tech-debt-mcp - Or configure npm for GitHub Packages (see Option 2 above)
npm ERR! 401 Unauthorized
Your GitHub token might be:
- Expired or invalid
- Missing the
read:packagesscope - Not properly configured in
.npmrc
Solution: Generate a new token with proper scopes.
If you get permission errors:
# Use a Node version manager (recommended)
nvm use 20
npm install -g tech-debt-mcp
# Or use sudo (not recommended)
sudo npm install -g tech-debt-mcpTo update to the latest version:
npm install -g tech-debt-mcp@latestOr for a specific version:
npm install -g tech-debt-mcp@1.0.0All releases are available at:
- npm Registry: https://www.npmjs.com/package/tech-debt-mcp
- GitHub Packages: https://github.com/PierreJanineh/TechDebtMCP/packages
If you encounter issues:
-
Check the logs:
tech-debt-mcp --version
-
Report on GitHub: https://github.com/PierreJanineh/TechDebtMCP/issues
-
Check the documentation: https://github.com/PierreJanineh/TechDebtMCP#readme
If you're developing Tech Debt MCP locally:
git clone https://github.com/PierreJanineh/TechDebtMCP.git
cd TechDebtMCP
npm install
npm run build
npm link # Makes `tech-debt-mcp` available globallynpm run dev # Run with ts-node
npm test # Run test suite
npm run watch # Watch mode# Update version in package.json
npm version patch|minor|major
# Create a git tag
git tag v$(npm pkg get version | tr -d '"')
# Push to trigger GitHub Actions (from develop branch)
git push origin develop --tagsThe CI/CD workflow will automatically:
- Run tests
- Build the project
- Publish to both npm and GitHub Packages
- Create a GitHub Release
Tech Debt MCP is licensed under the MIT License. See LICENSE for details.