Skip to content

Commit 7702745

Browse files
Knucklessg1Knucklessg1
committed
Added new standards.
1 parent c4f9e6f commit 7702745

File tree

6 files changed

+214
-55
lines changed

6 files changed

+214
-55
lines changed

‎.pre-commit-config.yaml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -27,13 +27,13 @@ repos:
2727
hooks:
2828
- id: black
2929
- repo: https://github.com/astral-sh/ruff-pre-commit
30-
rev: v0.15.4
30+
rev: v0.15.5
3131
hooks:
3232
- id: ruff
3333
types_or: [ python, pyi, jupyter ]
3434
args: ["--fix", "--ignore=E402"]
3535
- repo: https://github.com/codespell-project/codespell
36-
rev: v2.4.1
36+
rev: v2.4.2
3737
hooks:
3838
- id: codespell
3939
args: ["-L", "ans,linar,nam,tread,ot,"]

‎AGENTS.md‎

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
# AGENTS.md
2+
3+
## Tech Stack & Architecture
4+
- Language/Version: Python 3.10+
5+
- Core Libraries: `agent-utilities`, `fastmcp`, `pydantic-ai`
6+
- Key principles: Functional patterns, Pydantic for data validation, asynchronous tool execution.
7+
- Architecture:
8+
- `mcp.py`: Main MCP server entry point and tool registration.
9+
- `agent.py`: Pydantic AI agent definition and logic.
10+
- `skills/`: Directory containing modular agent skills (if applicable).
11+
- `agent/`: Internal agent logic and prompt templates.
12+
13+
### Architecture Diagram
14+
```mermaid
15+
graph TD
16+
User([User/A2A]) --> Server[A2A Server / FastAPI]
17+
Server --> Agent[Pydantic AI Agent]
18+
Agent --> Skills[Modular Skills]
19+
Agent --> MCP[MCP Server / FastMCP]
20+
MCP --> Client[API Client / Wrapper]
21+
Client --> ExternalAPI([External Service API])
22+
```
23+
24+
### Workflow Diagram
25+
```mermaid
26+
sequenceDiagram
27+
participant U as User
28+
participant S as Server
29+
participant A as Agent
30+
participant T as MCP Tool
31+
participant API as External API
32+
33+
U->>S: Request
34+
S->>A: Process Query
35+
A->>T: Invoke Tool
36+
T->>API: API Request
37+
API-->>T: API Response
38+
T-->>A: Tool Result
39+
A-->>S: Final Response
40+
S-->>U: Output
41+
```
42+
43+
## Commands (run these exactly)
44+
# Installation
45+
pip install .[all]
46+
47+
# Quality & Linting (run from project root)
48+
pre-commit run --all-files
49+
50+
# Execution Commands
51+
# documentdb-mcp\ndocumentdb_mcp.mcp:mcp_server\n# documentdb-agent\ndocumentdb_mcp.agent:agent_server
52+
53+
## Project Structure Quick Reference
54+
- MCP Entry Point → `mcp.py`
55+
- Agent Entry Point → `agent.py`
56+
- Source Code → `documentdb_mcp/`
57+
- Skills → `skills/` (if exists)
58+
59+
### File Tree
60+
```text
61+
├── .bumpversion.cfg\n├── .dockerignore\n├── .env\n├── .gitattributes\n├── .github\n│ └── workflows\n│ └── pipeline.yml\n├── .gitignore\n├── .pre-commit-config.yaml\n├── AGENTS.md\n├── Dockerfile\n├── LICENSE\n├── MANIFEST.in\n├── README.md\n├── compose.yml\n├── debug.Dockerfile\n├── documentdb_mcp\n│ ├── __init__.py\n│ ├── __main__.py\n│ ├── agent\n│ │ ├── AGENTS.md\n│ │ ├── CRON.md\n│ │ ├── HEARTBEAT.md\n│ │ ├── IDENTITY.md\n│ │ ├── MEMORY.md\n│ │ ├── USER.md\n│ │ └── templates.py\n│ ├── agent.py\n│ └── mcp.py\n├── mcp.compose.yml\n├── pyproject.toml\n├── pytest.ini\n└── requirements.txt
62+
```
63+
64+
## Code Style & Conventions
65+
**Always:**
66+
- Use `agent-utilities` for common patterns (e.g., `create_mcp_server`, `create_agent`).
67+
- Define input/output models using Pydantic.
68+
- Include descriptive docstrings for all tools (they are used as tool descriptions for LLMs).
69+
- Check for optional dependencies using `try/except ImportError`.
70+
71+
**Good example:**
72+
```python
73+
from agent_utilities import create_mcp_server
74+
from mcp.server.fastmcp import FastMCP
75+
76+
mcp = create_mcp_server("my-agent")
77+
78+
@mcp.tool()
79+
async def my_tool(param: str) -> str:
80+
"""Description for LLM."""
81+
return f"Result: {param}"
82+
```
83+
84+
## Dos and Don'ts
85+
**Do:**
86+
- Run `pre-commit` before pushing changes.
87+
- Use existing patterns from `agent-utilities`.
88+
- Keep tools focused and idempotent where possible.
89+
90+
**Don't:**
91+
- Use `cd` commands in scripts; use absolute paths or relative to project root.
92+
- Add new dependencies to `dependencies` in `pyproject.toml` without checking `optional-dependencies` first.
93+
- Hardcode secrets; use environment variables or `.env` files.
94+
95+
## Safety & Boundaries
96+
**Always do:**
97+
- Run lint/test via `pre-commit`.
98+
- Use `agent-utilities` base classes.
99+
100+
**Ask first:**
101+
- Major refactors of `mcp.py` or `agent.py`.
102+
- Deleting or renaming public tool functions.
103+
104+
**Never do:**
105+
- Commit `.env` files or secrets.
106+
- Modify `agent-utilities` or `universal-skills` files from within this package.
107+
108+
## When Stuck
109+
- Propose a plan first before making large changes.
110+
- Check `agent-utilities` documentation for existing helpers.

‎compose.yml‎

Lines changed: 9 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -1,61 +1,27 @@
11
---
22
services:
3-
documentdb-mcp:
4-
image: docker.io/knucklessg1/documentdb-mcp:latest
5-
# build: . # Debug
6-
container_name: documentdb-mcp
7-
hostname: documentdb-mcp
8-
command: [ "documentdb-mcp" ]
9-
extra_hosts:
10-
- "host.docker.internal:host-gateway"
11-
depends_on:
12-
- documentdb
13-
logging:
14-
driver: json-file
15-
options:
16-
max-size: "10m"
17-
max-file: "3"
18-
restart: always
19-
env_file:
20-
- .env
21-
22-
environment:
23-
- "PYTHONUNBUFFERED=1"
24-
- "HOST=0.0.0.0"
25-
- "PORT=8015"
26-
- "TRANSPORT=streamable-http"
27-
- "MONGODB_URI=${MONGODB_URI}" # Required
28-
ports:
29-
- "8015:8015"
30-
healthcheck:
31-
test: [ "CMD", "python3", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8015/health')" ]
32-
interval: 30s
33-
timeout: 10s
34-
retries: 3
35-
start_period: 10s
36-
373
documentdb-agent:
38-
image: docker.io/knucklessg1/documentdb-mcp:latest
39-
# build: . # Debug
4+
# image: docker.io/knucklessg1/documentdb-mcp:latest
5+
build:
6+
context: .
7+
dockerfile: debug.Dockerfile
408
container_name: documentdb-agent
419
hostname: documentdb-agent
4210
command: [ "documentdb-agent" ]
4311
extra_hosts:
4412
- "host.docker.internal:host-gateway"
45-
depends_on:
46-
- documentdb-mcp
4713
logging:
4814
driver: json-file
4915
options:
5016
max-size: "10m"
5117
max-file: "3"
5218
restart: always
53-
5419
environment:
5520
- "PYTHONUNBUFFERED=1"
5621
- "HOST=0.0.0.0"
57-
- "PORT=9015"
58-
- "MCP_URL=http://documentdb-mcp:8015/mcp"
22+
- "PORT=9435"
23+
- "TRANSPORT=stdio"
24+
- "MONGODB_URI=${MONGODB_URI}"
5925
- "PROVIDER=openai"
6026
- "LLM_BASE_URL=${LLM_BASE_URL:-http://host.docker.internal:1234/v1}"
6127
- "LLM_API_KEY=${LLM_API_KEY:-llama}"
@@ -64,9 +30,9 @@ services:
6430
- "ENABLE_WEB_UI=True"
6531
- "ENABLE_OTEL=True"
6632
ports:
67-
- "9015:9015"
33+
- "9435:9435"
6834
healthcheck:
69-
test: [ "CMD", "python3", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:9015/health')" ]
35+
test: [ "CMD", "python3", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:9435/health')" ]
7036
interval: 30s
7137
timeout: 10s
7238
retries: 3
@@ -76,7 +42,6 @@ services:
7642
image: ghcr.io/microsoft/documentdb/documentdb-local:latest
7743
container_name: documentdb
7844
hostname: documentdb
79-
8045
environment:
8146
- "PYTHONUNBUFFERED=1"
8247
- USERNAME=${DOCUMENTDB_USERNAME:-administrator}

‎documentdb_mcp/agent/IDENTITY.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,8 +7,9 @@
77
* **Vibe:** Data-driven, technical, methodical
88

99
### System Prompt
10-
You must use the `mcp-client` universal skill and refer to `documentdb-mcp.md` for available tags/tools.
1110
You are the DocumentDB Agent.
11+
You must always first run `list_skills` to show all skills.
12+
Then, use the `mcp-client` universal skill and check the reference documentation for `documentdb-mcp.md` to discover the exact tags and tools available for your capabilities.
1213
Your goal is to assist the user with database operations on DocumentDB or MongoDB.
1314
You handle collection management, CRUD operations, database analysis, and user management.
1415
Help the user interact with their data efficiently and securely.

‎documentdb_mcp/mcp_config.json‎

Lines changed: 0 additions & 8 deletions
This file was deleted.

‎mcp.compose.yml‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
---
2+
services:
3+
documentdb-mcp:
4+
image: docker.io/knucklessg1/documentdb-mcp:latest
5+
# build: . # Debug
6+
container_name: documentdb-mcp
7+
hostname: documentdb-mcp
8+
command: [ "documentdb-mcp" ]
9+
extra_hosts:
10+
- "host.docker.internal:host-gateway"
11+
depends_on:
12+
- documentdb
13+
logging:
14+
driver: json-file
15+
options:
16+
max-size: "10m"
17+
max-file: "3"
18+
restart: always
19+
env_file:
20+
- .env
21+
environment:
22+
- "PYTHONUNBUFFERED=1"
23+
- "HOST=0.0.0.0"
24+
- "PORT=8015"
25+
- "TRANSPORT=streamable-http"
26+
- "MONGODB_URI=${MONGODB_URI}" # Required
27+
ports:
28+
- "8015:8015"
29+
healthcheck:
30+
test: [ "CMD", "python3", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8015/health')" ]
31+
interval: 30s
32+
timeout: 10s
33+
retries: 3
34+
start_period: 10s
35+
36+
documentdb-agent:
37+
image: docker.io/knucklessg1/documentdb-mcp:latest
38+
# build: . # Debug
39+
container_name: documentdb-agent
40+
hostname: documentdb-agent
41+
command: [ "documentdb-agent" ]
42+
extra_hosts:
43+
- "host.docker.internal:host-gateway"
44+
depends_on:
45+
- documentdb-mcp
46+
logging:
47+
driver: json-file
48+
options:
49+
max-size: "10m"
50+
max-file: "3"
51+
restart: always
52+
environment:
53+
- "PYTHONUNBUFFERED=1"
54+
- "HOST=0.0.0.0"
55+
- "PORT=9015"
56+
- "MCP_URL=http://documentdb-mcp:8015/mcp"
57+
- "PROVIDER=openai"
58+
- "LLM_BASE_URL=${LLM_BASE_URL:-http://host.docker.internal:1234/v1}"
59+
- "LLM_API_KEY=${LLM_API_KEY:-llama}"
60+
- "MODEL_ID=${MODEL_ID:-qwen/qwen3-coder-next}"
61+
- "DEBUG=False"
62+
- "ENABLE_WEB_UI=True"
63+
- "ENABLE_OTEL=True"
64+
ports:
65+
- "9015:9015"
66+
healthcheck:
67+
test: [ "CMD", "python3", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:9015/health')" ]
68+
interval: 30s
69+
timeout: 10s
70+
retries: 3
71+
start_period: 10s
72+
73+
documentdb:
74+
image: ghcr.io/microsoft/documentdb/documentdb-local:latest
75+
container_name: documentdb
76+
hostname: documentdb
77+
environment:
78+
- "PYTHONUNBUFFERED=1"
79+
- USERNAME=${DOCUMENTDB_USERNAME:-administrator}
80+
- PASSWORD=${DOCUMENTDB_PASSWORD:-documentdbadmin}
81+
extra_hosts:
82+
- "host.docker.internal:host-gateway"
83+
volumes:
84+
- ./mcp/documentdb-data:/data
85+
logging:
86+
driver: json-file
87+
options:
88+
max-size: "10m"
89+
max-file: "3"
90+
ports:
91+
- "10260:10260"

0 commit comments

Comments
 (0)