# Contributing to Counsel MCP Server
Thank you for your interest in contributing to the Counsel MCP Server! This document provides guidelines and information for contributors.
## Code of Conduct
Please be respectful and constructive in all interactions. We're building something together.
## Getting Started
### Prerequisites
- Node.js 18+
- npm 9+
- Git
### Development Setup
1. Fork the repository on GitHub
2. Clone your fork locally:
```bash
git clone https://github.com/YOUR_USERNAME/counsel-mcp-server.git
cd counsel-mcp-server
```
3. Install dependencies:
```bash
npm install
```
4. Build the project:
```bash
npm run build
```
5. Run tests:
```bash
npm test
```
### Running Locally
```bash
npm run start
```
The server will start at `http://localhost:3000`.
## Development Workflow
### Branching
- Create a feature branch from `main`:
```bash
git checkout -b feature/your-feature-name
```
- Use descriptive branch names: `feature/add-new-tool`, `fix/oauth-redirect`, `docs/update-readme`
### Making Changes
1. Make your changes in the appropriate files
2. Follow existing code style and patterns
3. Add tests for new functionality
4. Update documentation if needed
### Code Style
- **TypeScript**: Use strict mode, proper types (avoid `any`)
- **ES Modules**: Use `.js` extension in imports
- **Formatting**: Follow existing patterns (consider adding Prettier in the future)
- **Naming**: Use descriptive names, camelCase for variables/functions, PascalCase for types/classes
### Testing
Run the test suite before submitting:
```bash
npm test
```
For watch mode during development:
```bash
npm run test:watch
```
### Committing
- Write clear, concise commit messages
- Use present tense: "Add feature" not "Added feature"
- Reference issues when applicable: "Fix OAuth redirect (#123)"
### Security Checks
This project includes automated secret detection to prevent accidental leakage of API keys and tokens.
**Pre-commit Hook**
A pre-commit hook automatically scans staged files for potential secrets before each commit. If secrets are detected, the commit will be blocked.
**Manual Security Scan**
```bash
# Scan staged files
npm run security:check
# Scan all tracked files
npm run security:check:all
```
**Detected Patterns**
The scanner detects:
- API keys and secret keys
- Bearer tokens
- AWS credentials
- GitHub tokens (PAT, OAuth, etc.)
- npm tokens
- Slack tokens
- Stripe keys
- Private keys
- Passwords and generic tokens
**False Positives**
If you encounter a false positive:
1. Add the file pattern to `.secretsignore`
2. Use placeholder values like `your_api_key_here`
3. Reference environment variables (`process.env.API_KEY`)
## Adding New Tools
Tools are the core functionality of the MCP server. To add a new tool:
1. Create or edit a file in `src/tools/`:
```typescript
import { z } from "zod";
import { apiClient } from "../client.js";
export const TOOLS = {
my_new_tool: {
name: "my_new_tool",
description: "Clear description of what this tool does",
schema: {
param1: z.string().describe("Description of param1"),
param2: z.number().optional().describe("Optional param2"),
},
handler: async (args: { param1: string; param2?: number }) => {
const response = await apiClient.post("/endpoint", args);
return {
content: [{
type: "text" as const,
text: JSON.stringify(response.data, null, 2)
}]
};
}
}
};
```
2. Import and register in `src/index.ts`:
```typescript
import { TOOLS as MY_TOOLS } from "./tools/my_tools.js";
// In the start action:
for (const tool of Object.values(MY_TOOLS)) {
mcpServer.tool(tool.name, tool.schema, tool.handler);
}
```
3. Add tests in `tests/`:
```typescript
import { describe, it, expect } from 'vitest';
describe('my_new_tool', () => {
it('should do something', async () => {
// Test implementation
});
});
```
## Submitting Changes
### Pull Request Process
1. Ensure all tests pass
2. Update documentation if needed
3. Push to your fork:
```bash
git push origin feature/your-feature-name
```
4. Open a Pull Request against `main`
5. Fill out the PR template with:
- Description of changes
- Related issues
- Testing performed
### PR Review
- PRs require review before merging
- Address review feedback promptly
- Keep discussions constructive
## Reporting Issues
### Bug Reports
Include:
- Description of the bug
- Steps to reproduce
- Expected vs actual behavior
- Environment (Node version, OS, MCP client)
- Relevant logs or error messages
### Feature Requests
Include:
- Description of the feature
- Use case / motivation
- Proposed implementation (if any)
## Questions?
- Open a [GitHub Discussion](https://github.com/mercurialsolo/counsel-mcp/discussions)
- Check existing issues and discussions first
## License
By contributing, you agree that your contributions will be licensed under the MIT License.
