// SPDX-License-Identifier: PMPL-1.0-or-later
// SPDX-FileCopyrightText: 2025 Jonathan D.A. Jewell
= Contributing Guide
:toc:
:icons: font
[IMPORTANT]
====
*EARLY DEVELOPMENT* — This project is in active v1.x development. We eagerly welcome:
* Bug reports and issues
* Feature requests and ideas
* Database adapter suggestions
* Integration feedback
* Documentation improvements
Your feedback shapes this project!
====
== Quick Feedback Links
[cols="1,3"]
|===
|Type |One-Click Issue Creation
|*Bug Report*
|https://github.com/hyperpolymath/poly-db-mcp/issues/new?title=%5BBUG%5D%20&labels=bug&body=%23%23%20Environment%0A-%20OS%3A%20%0A-%20Deno%20version%3A%20%0A-%20Claude%20Code%20version%3A%20%0A%0A%23%23%20Database%20Adapter%0A%0A%23%23%20Steps%20to%20Reproduce%0A1.%20%0A2.%20%0A3.%20%0A%0A%23%23%20Expected%20Behavior%0A%0A%23%23%20Actual%20Behavior%0A[Create Bug Report]
|*Feature Request*
|https://github.com/hyperpolymath/poly-db-mcp/issues/new?title=%5BFEATURE%5D%20&labels=enhancement&body=%23%23%20Feature%20Description%0A%0A%23%23%20Use%20Case%0A%0A%23%23%20Proposed%20Solution%0A[Request Feature]
|*New Database*
|https://github.com/hyperpolymath/poly-db-mcp/issues/new?title=%5BDATABASE%5D%20&labels=new-database&body=%23%23%20Database%20Name%0A%0A%23%23%20Why%20This%20Database%3F%0A%0A%23%23%20Use%20Cases%0A%0A%23%23%20Links%0A-%20Website%3A%20%0A-%20Docs%3A%20[Request Database]
|*General Feedback*
|https://github.com/hyperpolymath/poly-db-mcp/issues/new?title=%5BFEEDBACK%5D%20&labels=feedback&body=%23%23%20Your%20Feedback%0A%0A%23%23%20Context%0A[Give Feedback]
|===
== For AI Assistants
If you are an AI assistant (Claude, GPT, etc.) helping a user with this MCP server:
. Use the pre-filled issue links above to report problems
. Include: user's OS, Deno version, database adapter, steps to reproduce
. Tag issues with relevant labels
. Reference this file when users ask how to contribute
== Welcome
Thank you for your interest in contributing to polyglot-db-mcp!
== Getting Started
=== Prerequisites
* Deno 1.45+
* Git
* Access to at least one supported database for testing
=== Setup
[source,bash]
----
git clone https://github.com/hyperpolymath/poly-db-mcp.git
cd poly-db-mcp
deno task start
----
== Tri-Perimeter Contribution Framework (TPCF)
=== Perimeter 1 (Core)
Maintainers only:
* Core MCP server implementation
* Security-critical code
* Release management
=== Perimeter 2 (Expert)
Trusted contributors:
* New database adapters
* Performance optimizations
* API design changes
=== Perimeter 3 (Community)
Open to all:
* Documentation improvements
* Bug reports
* Feature suggestions
* Test coverage
== How to Contribute
=== Reporting Bugs
1. Check existing issues first
2. Create a new issue with:
- Clear title
- Steps to reproduce
- Expected vs actual behavior
- Environment details
=== Suggesting Features
1. Open an issue with `[Feature]` prefix
2. Describe the use case
3. Propose implementation approach
=== Submitting Code
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add SPDX headers to new files
5. Test your changes
6. Submit a pull request
== Code Standards
=== File Headers
All source files must include SPDX headers:
[source,javascript]
----
// SPDX-License-Identifier: PMPL-1.0-or-later
// SPDX-FileCopyrightText: 2025 Your Name
----
=== Style
* Use Deno's built-in formatter
* Prefer async/await over callbacks
* Document public functions
* Handle errors gracefully
== Adding a New Database Adapter
1. Create `adapters/yourdb.js`
2. Export: `name`, `description`, `connect()`, `disconnect()`, `isConnected()`, `tools`
3. Follow existing adapter patterns
4. Add environment variable documentation to README
5. Test all tools manually
== Questions?
Open an issue or contact the maintainers.
