Skip to content

Commit a47b492

Browse files
NeurArkNeurArk
authored
docs(project): add AGENTS.md guidelines for AI coding agents (#18)
Add comprehensive guidelines for coding agents working on the MCP Data Assistant project. This document provides: - Environment setup requirements and variables - Quality gate standards using pytest, ruff, mypy, and bandit - GitHub workflow compatibility rules - Project structure documentation - Coding standards aligned with project conventions - MCP-specific guidelines for tool development - Commit conventions and PR rules - Testing guidelines and troubleshooting steps The document is designed for use with AI coding agents in containerized environments without internet access after initial configuration.
1 parent 1d7f508 commit a47b492

1 file changed

Lines changed: 188 additions & 0 deletions

File tree

‎AGENTS.md‎

Lines changed: 188 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,188 @@
1+
# AGENTS.md – Guidelines for the MCP Data Assistant Agent
2+
3+
> **Read this entire file before performing any action.** Failing to follow these rules may invalidate the task.
4+
5+
---
6+
7+
## 1. Environment initialization
8+
9+
Dependencies are automatically installed via the agent interface during the configuration phase.
10+
The wheelhouse directory contains all required packages for offline installation.
11+
12+
* Required environment variables:
13+
- `PYTHONPATH`: Set to `.`
14+
- `PROJECT_ROOT`: Set to `/workspace/mcp-data-assistant`
15+
16+
* Optional secrets:
17+
- `OPENAI_API_KEY`: Required only if using OpenAI models (not needed for Ollama)
18+
19+
---
20+
21+
## 2. Quality gates (run in this order)
22+
23+
```bash
24+
pytest -q --cov=tools --cov=agent --cov-report=term-missing --cov-fail-under=85 # tests and coverage ≥ 85%
25+
ruff check . # code formatting and linting
26+
ruff format --check . # code formatting check
27+
mypy tools/ agent/ tests/ --python-version 3.12 # strict typing
28+
bandit -r tools/ agent/ -ll -x /tests/ # security scan
29+
```
30+
31+
All commands must return exit code 0. Fix any failing gate **before committing**.
32+
33+
---
34+
35+
## 3. GitHub workflow compatibility
36+
37+
This project follows GitHub Actions CI/CD standards:
38+
39+
* All PRs must pass automated checks
40+
* CI pipeline runs the quality gates listed above
41+
* Commits must follow conventional commit format
42+
* Branch protection requires PR reviews before merging to `main`
43+
44+
---
45+
46+
## 4. Project structure
47+
48+
| Directory | Purpose |
49+
| ---------- | ----------------------------------------------------- |
50+
| `agent/` | LLM assistant logic and session management |
51+
| `tools/` | Core MCP tools (SQL, CSV, PDF) |
52+
| `tests/` | Unit and integration tests |
53+
| `static/` | Static assets including MCP schema |
54+
| `data/` | Sample datasets for testing |
55+
| `reports/` | Generated PDF reports |
56+
57+
---
58+
59+
## 5. Coding standards
60+
61+
| Topic | Mandatory rules |
62+
| ---------- | ------------------------------------------------------------------------------------- |
63+
| Format | Use **ruff format** (line length 120) and **ruff check**. |
64+
| Typing | Provide complete hints. `mypy --strict` must succeed without unjustified ignores. |
65+
| Tests | Every bug fix or feature requires unit tests. Minimum 85% coverage required. |
66+
| Logs | Use the `logging` module, never `print`. |
67+
| Security | Avoid `eval`, plain secrets and unclean temp files. Follow OWASP guidelines. |
68+
| Imports | Use absolute imports for project modules. |
69+
| Docstrings | Google style docstrings for all public functions/classes. |
70+
71+
---
72+
73+
## 6. MCP-specific guidelines
74+
75+
* Maintain MCP schema in `static/schema.json` for all tool changes
76+
* Follow Model Context Protocol standards for tool implementation
77+
* Ensure tools are stateless and idempotent
78+
* Implement proper error handling with meaningful MCP error responses
79+
80+
---
81+
82+
## 7. Commit convention
83+
84+
```
85+
<type>(<scope>): <short summary>
86+
87+
<body if needed – 72 chars/line>
88+
89+
BREAKING CHANGE: <explanation>
90+
```
91+
92+
*Allowed types*: `feat`, `fix`, `perf`, `refactor`, `test`, `docs`, `chore`, `ci`.
93+
*Scope* should point to a module (e.g. `agent`, `tools`, `sql`, `csv`, `pdf`).
94+
Make commits atomic: one change, one green test.
95+
96+
---
97+
98+
## 8. Pull request rules
99+
100+
1. Create a branch named `feat/<issue-id>-slug` or `fix/<issue-id>-slug`.
101+
2. Open a PR to `main` and include:
102+
* **What**: short summary
103+
* **Why**: business need or bug
104+
* **How**: technical approach (include diagrams if useful)
105+
* **Test Plan**: commands and test cases covered
106+
* **MCP Impact**: schema changes or tool behavior changes
107+
3. Ensure all quality gates pass **before** requesting review.
108+
4. Update `CHANGELOG.md` when needed; add a new `## [Unreleased]` section.
109+
5. Link the PR to the related issue.
110+
111+
---
112+
113+
## 9. Standard workflow
114+
115+
1. **Analyze** the issue or description.
116+
2. **Plan** your work (files, steps) and post the plan as a comment in the issue.
117+
3. **Check** existing tests for context and patterns.
118+
4. **Implement** in small units (functions < 30 lines).
119+
5. Run all quality gates locally (section 2).
120+
6. Commit following the convention (section 7).
121+
7. Push the branch, open the PR and ensure CI is green.
122+
8. Request review once all checks pass.
123+
124+
---
125+
126+
## 10. Tool development checklist
127+
128+
When developing MCP tools:
129+
130+
- [ ] Tool inherits from appropriate base class
131+
- [ ] Implements required MCP protocol methods
132+
- [ ] Returns properly formatted JSON responses
133+
- [ ] Handles edge cases gracefully
134+
- [ ] Includes comprehensive test coverage
135+
- [ ] Updates schema.json if adding new tool
136+
- [ ] Add tool documentation to README.md
137+
138+
---
139+
140+
## 11. Assistant development
141+
142+
When working on the Assistant module:
143+
144+
- [ ] Maintain conversation history properly
145+
- [ ] Handle model switching (OpenAI/Ollama) gracefully
146+
- [ ] Implement proper error recovery
147+
- [ ] Test with both model backends
148+
- [ ] Ensure session cleanup
149+
- [ ] Handle API key absence for Ollama mode
150+
151+
---
152+
153+
## 12. Quick troubleshooting
154+
155+
| Failure | Immediate action |
156+
| --------------------------- | ---------------------------------------------------------- |
157+
| ImportError | Check if package is in requirements.txt and wheelhouse/ |
158+
| Coverage < 85% | Add missing tests or justify the drop in the PR. |
159+
| mypy errors | Add type hints or refactor the code. |
160+
| Tool execution fails | Check schema.json alignment with implementation. |
161+
| Assistant connection errors | Verify OPENAI_API_KEY or Ollama service status. |
162+
| CI pipeline fails | Check GitHub Actions logs and fix locally first. |
163+
164+
---
165+
166+
## 13. Testing guidelines
167+
168+
* Write tests first (TDD approach encouraged)
169+
* Use pytest fixtures for common setup
170+
* Mock external services (OpenAI, Ollama)
171+
* Test both success and failure paths
172+
* Use parameterized tests for multiple scenarios
173+
* Ensure tests are deterministic
174+
175+
---
176+
177+
## 14. Environment considerations
178+
179+
* The project supports Python 3.12+
180+
* SQLite and PostgreSQL database support
181+
* Gradio 5.29+ for UI
182+
* ReportLab for PDF generation
183+
* Ollama integration for local models
184+
* All dependencies pre-downloaded in wheelhouse/
185+
186+
---
187+
188+
**Remember:** *Clean, tested, documented code; no shortcuts. MCP tools must be reliable and stateless. Always ensure GitHub workflow compliance.*

0 commit comments

Comments
 (0)