Skip to content

Commit 104c5dd

Browse files
crivetimihaicrivetimihai
committed
Update developer setup page
Signed-off-by: Mihai Criveti <[email protected]>
1 parent ef35f46 commit 104c5dd

File tree

1 file changed

+133
-22
lines changed

1 file changed

+133
-22
lines changed

‎docs/docs/development/index.md

Lines changed: 133 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -1,47 +1,158 @@
11
# Development
22

3-
This section is for developers and contributors working on MCP Gateway itself — whether you're adding features, fixing bugs, or building custom integrations.
3+
Welcome! This guide is for developers contributing to MCP Gateway. Whether you're fixing bugs, adding features, or extending federation or protocol support, this doc will help you get up and running quickly and consistently.
44

55
---
66

77
## 🧰 What You'll Find Here
88

9-
| Page | Description |
10-
|------|-------------|
11-
| [Building Locally](building.md) | How to install dependencies, set up a virtual environment, and run the gateway |
12-
| [Packaging](packaging.md) | How to build a release, container image, or prebuilt binary |
9+
| Page | Description |
10+
| --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
11+
| [Building Locally](building.md) | How to install dependencies, set up a virtual environment, and run the gateway |
12+
| [Packaging](packaging.md) | How to build a release, container image, or prebuilt binary |
13+
| [DEVELOPING.md](https://github.com/IBM/mcp-context-forge/blob/main/DEVELOPING.md) | Coding standards, commit conventions, and review workflow |
1314

1415
---
1516

1617
## 🛠 Developer Environment
1718

1819
MCP Gateway is built with:
1920

20-
- **Python 3.10+**
21-
- **FastAPI**
22-
- **Pydantic Settings**
23-
- **SQLAlchemy (async)**
24-
- **HTMX + Alpine.js + Tailwind (for UI)**
21+
* **Python 3.10+**
22+
* **FastAPI** + **SQLAlchemy (async)** + **Pydantic Settings**
23+
* **HTMX**, **Alpine.js**, **TailwindCSS** for the Admin UI
2524

26-
Development tools include:
25+
Development tools:
2726

28-
- `ruff`, `mypy`, `black`, `isort` for linting and formatting
29-
- `pytest` and `httpx` for tests
30-
- `uvicorn` and `gunicorn` for serving the app
27+
* Linters: `ruff`, `mypy`, `black`, `isort`
28+
* Testing: `pytest`, `httpx`
29+
* Serving: `uvicorn`, `gunicorn`
30+
31+
Code style and consistency is enforced via:
32+
33+
```bash
34+
make lint # runs ruff, mypy, black, isort
35+
make pre-commit # runs pre-commit hooks on staged files
36+
```
37+
38+
As well as GitHub Actions code scanning.
39+
40+
---
41+
42+
## 🧪 Testing
43+
44+
Test coverage includes:
45+
46+
* Unit tests under `tests/unit/`
47+
* Integration tests under `tests/integration/`
48+
* End-to-end tests under `tests/e2e/`
49+
* Example payload performance testing under `tests/hey/`
50+
51+
Use:
52+
53+
```bash
54+
make test # run all tests
55+
make test-unit # run only unit tests
56+
make test-e2e # run end-to-end
57+
```
58+
59+
---
60+
61+
## 🔍 Linting and Hooks
62+
63+
CI will fail your PR if code does not pass lint checks.
64+
65+
You should manually run:
66+
67+
```bash
68+
make lint
69+
make pre-commit
70+
```
71+
72+
Enable hooks with:
73+
74+
```bash
75+
pre-commit install
76+
```
77+
78+
---
79+
80+
## 🐳 Containers
81+
82+
Build and run with Podman or Docker:
83+
84+
```bash
85+
make podman # build production image
86+
make podman-run-ssl # run with self-signed TLS at https://localhost:4444
87+
```
3188

3289
---
3390

34-
## 💡 Development Philosophy
91+
## 🔐 Authentication
92+
93+
Admin UI and API are protected by Basic Auth or JWT.
94+
95+
To generate a JWT:
96+
97+
```bash
98+
python -m mcpgateway.utils.create_jwt_token \
99+
-u admin \
100+
-e 10080 | tee token.txt
101+
102+
export MCPGATEWAY_BEARER_TOKEN=$(cat token.txt)
103+
```
104+
105+
Then test:
106+
107+
```bash
108+
curl -k -sX GET \
109+
-H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \
110+
https://localhost:4444/tools | jq
111+
```
112+
113+
---
114+
115+
## 📦 Configuration
116+
117+
Edit `.env` or set environment variables. A complete list is documented in the [README](https://github.com/IBM/mcp-context-forge#configuration-env-or-env-vars).
35118

36-
This project prioritizes:
119+
Use:
37120

38-
- **Strict API consistency** with the MCP protocol
39-
- **Composable internals** (service modules, dependency injection)
40-
- **Production-first** design (SSL, metrics, rate limits, etc.)
41-
- **Dev-friendly tools** (Makefile, pre-commit hooks, typed config)
121+
```bash
122+
cp .env.example .env
123+
```
124+
125+
Key configs include:
126+
127+
| Variable | Purpose |
128+
| ------------------- | ---------------------------- |
129+
| `DATABASE_URL` | Database connection |
130+
| `JWT_SECRET_KEY` | Signing key for JWTs |
131+
| `DEV_MODE=true` | Enables hot reload and debug |
132+
| `CACHE_TYPE=memory` | Options: memory, redis, none |
133+
134+
---
135+
136+
## 🚧 Contribution Tips
137+
138+
* Pick a [`good first issue`](https://github.com/IBM/mcp-context-forge/issues?q=is%3Aissue+label%3A%22good+first+issue%22+is%3Aopen)
139+
* Read the [`CONTRIBUTING.md`](https://github.com/IBM/mcp-context-forge/blob/main/CONTRIBUTING.md)
140+
* Fork, branch, commit with purpose
141+
* Submit PRs against `main` with clear titles and linked issues
42142

43143
---
44144

45-
## 🚧 Contribution Guidelines
145+
## ✅ CI/CD
146+
147+
GitHub Actions enforce:
148+
149+
* CodeQL security scanning
150+
* Pre-commit linting
151+
* Dependency audits
152+
* Docker image builds
153+
154+
CI configs live in `.github/workflows/`.
155+
156+
---
46157

47-
Please see [`DEVELOPING.md`](https://github.com/your-org/your-repo/blob/main/DEVELOPING.md) for coding standards, commit conventions, and review workflow.
158+
Let me know if you'd like a shorter version or want to customize for internal team handoff.

0 commit comments

Comments
 (0)