Content
# Tool List
> Before further development, please read [SPECDEV](docs/SPECDEV.md). The project route has shifted from a simple chat console to MCP Agent Workspace: uploading a project can generate a structured review report, and can also regularly call MCP tools to generate results and push them to Feishu or Enterprise WeChat.
A web-based intelligent agent console based on FastAPI, React, and Pydantic Deep Agents. Users can have multi-round conversations with the Agent in the browser, upload files or folders as workspace context, and view Skill, MCP status, tool calls, execution status, and session history in real-time.
> Note: The `pydantic-deepagents` mentioned in the requirements corresponds to the Pydantic Deep Agents project semantics; the current public PyPI package name is `pydantic-deep`, and the import name is `pydantic_deep`.
## Product Direction and Current Capabilities
- Multi-round dialogue, session creation, reset, renaming, and deletion
- Dialogue box is the only functional entrance: all capabilities are triggered through natural language or `/` slash commands
- Slash commands: `/help` `/audit [security|testing|deployment|architecture]` `/issues` `/report` `/export json|markdown` `/schedule` `/connect github` `/disconnect github` `/mcp`, input `/` automatic completion
- Top-right task/file/tool/report drawer, only responsible for managing structured objects formed during the chat process
- MCP connection management center: all authorization is completed within the interface, no need to modify `.env`. GitHub supports pasting Personal Access Token or OAuth App authorization; Gmail supports filling in Google OAuth Client and authorizing within the interface; interface credentials are saved in the local database (app_settings), and environment variable configuration takes priority
- Gmail timed briefing: `18:00 every day to summarize Gmail unread emails and extract tasks` → conversational creation → unread list → LLM Chinese summary of each seal + task extraction → Feishu/Enterprise WeChat push; default read-only scope, sending emails belongs to confirmation-based writing operation
- Project Audit: upload project → `/audit` initiate → multi-round deep excavation → issue pool → status marking → `/report` generate structured report → `/export` export to other platforms
- Review report export: JSON / Markdown / HTML / PDF, product saved as artifact and report history retained
- Special review Skill: security-audit / test-readiness / deployment-readiness (registry records source, license, version, allowed tools)
- Scheduler: conversational creation, conversational modification (“change this task to 6 pm every day” → patch confirmation card), manual operation, operation record
- Scheduling operation: failed automatic retry (`SCHEDULE_RUN_RETRIES`), operation timeout marked failure (`SCHEDULE_RUN_TIMEOUT_SECONDS`), restart and resume pending tasks
- Feishu/Enterprise WeChat Webhook push and test push, super long message automatic split
- MCP Server: GitHub (read + write), Tavily search, Fetch webpage content reading
- SQLite / MySQL dual storage: `STORAGE_BACKEND=sqlite|mysql`, 18 tables (schedule, run, audit, artifact, tool permissions, tool logs, app_settings, chat sessions, uploaded file indexes, OAuth connections)
- Chat session and uploaded file persistence: backend restart and chat context and uploaded project automatic water-heated recovery
- Local development default SQLite; public network deployment switch to MySQL (`.env` fill `MYSQL_*` + `STORAGE_BACKEND=mysql`, first startup automatic table creation)
- Frontend testing (vitest + testing-library) and Playwright browser E2E script (`npm run e2e`)
<details>
<summary>Original Capability List</summary>
- Multi-round dialogue, session creation, reset, renaming, and deletion
- Target information architecture: a unified chat entrance, Project Audit and timed tasks are triggered from chat
- Target management method: top-right task/file/tool/report drawer management structured objects
- Project Audit: read uploaded files, review sessions, issue pool, issue status, structured reports, JSON/Markdown export
- Scheduler: conversational task planning, confirmation and saving, manual operation, operation record
- Scheduler supports page configuration Feishu/Enterprise WeChat Webhook, save and then Run now and background scheduler will use the selected channel push
- SQLite persistence: save schedule, run, audit session, issue, report
- Single-process background scheduler: run according to `next_run_at` to the point of enabled tasks
- Feishu/Enterprise WeChat Webhook push and test push
- Tavily search client
- Left session history column, can be folded
- Right work tree, can expand folder, preview code/text file
- File/folder multipart upload, retain relative path
- Pydantic Deep `create_deep_agent(...)` + `agent.iter(...)` native execution link
- Skill registered to `SkillsToolset` through `skill_directories=[backend/skills]`
- Agent can read uploaded files through `read_file` / `grep` / `glob` and other file tools
- Tool call log and light execution prompt above the input box
- MCP Server configuration, status display, and GitHub MCP. Public GitHub read does not require token configuration, private repository, higher limit or write operation requires GitHub OAuth / `GITHUB_TOKEN`
- GitHub MCP covers repo, file, issue, PR, Actions, code search, labels, projects, branches, tags, contributors, rate limit query
- GitHub write operation supports creating issue, commenting issue/PR, adding labels, merging PR, default must confirm and record audit log
- DeepSeek direct stream downgrade link
- Frontend Codex style workstation layout and Three.js dot matrix background
</details>
## Technical Stack
```text
Frontend:
React + TypeScript + Vite
Tailwind CSS
Framer Motion
lucide-react
Three.js
Backend:
Python 3.10+
FastAPI
Pydantic / pydantic-settings
pydantic-deep
DeepSeek OpenAI-compatible API
Runtime:
SKILL.md local Skill
Pydantic Deep SkillsToolset
Pydantic Deep filesystem tools
In-memory SessionStore
Mock MCP config
Local stdio GitHub MCP server
```
## Project Structure
```text
.
├── backend/
│ ├── app/
│ │ ├── api/ # chat/session/upload/skill/mcp routes
│ │ ├── core/ # agent factory, runner, prompts, sessions, config
│ │ ├── mcp/ # MCP config, mock status, GitHub stdio MCP server
│ │ ├── schemas/ # API DTOs
│ │ └── skills/ # skill discovery endpoint support
│ ├── skills/
│ │ ├── code-review/
│ │ ├── test-generator/
│ │ ├── data-analysis/
│ │ └── documentation-writer/
│ ├── tests/
│ ├── mcp_servers.json
│ └── pyproject.toml
│
├── frontend/
│ ├── src/
│ │ ├── api/
│ │ ├── components/
│ │ ├── components/ui/
│ │ ├── lib/
│ │ ├── styles/
│ │ └── types.ts
│ └── package.json
│
├── .env.example
└── README.md
```
## Quick Start
### 1. Configure Environment Variables
```bash
cp .env.example .env
```
`.env` example:
```env
DEEPSEEK_API_KEY=your-key
DEEPSEEK_BASE_URL=https://api.deepseek.com
DEEPSEEK_MODEL=deepseek-v4-flash
GITHUB_TOKEN=your-github-token
GITHUB_CLIENT_ID=your-github-oauth-app-client-id
GITHUB_CLIENT_SECRET=your-github-oauth-app-client-secret
GITHUB_OAUTH_REDIRECT_URL=http://127.0.0.1:8010/api/github/oauth/callback
FRONTEND_BASE_URL=http://127.0.0.1:5175
TAVILY_API_KEY=your-tavily-key
FEISHU_WEBHOOK_URL=https://open.feishu.cn/open-apis/bot/v2/hook/xxx
WECOM_WEBHOOK_URL=https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxx
DATABASE_PATH=backend/data/agent_workspace.sqlite3
STORAGE_BACKEND=sqlite
MYSQL_HOST=127.0.0.1
MYSQL_PORT=3306
MYSQL_USER=
MYSQL_PASSWORD=
MYSQL_DATABASE=agent_console
SKILLS_DIR=backend/skills
MCP_CONFIG_PATH=backend/mcp_servers.json
VITE_API_PROXY_TARGET=http://127.0.0.1:8010
```
`FEISHU_WEBHOOK_URL` is the Feishu group custom robot Webhook address, and the current Scheduler defaults to using Feishu push. `WECOM_WEBHOOK_URL` is the Enterprise WeChat group robot Webhook address, retained as a compatible channel. Please do not submit real keys.
### 2. Start Backend
`pydantic-deep` requires Python 3.10+, and Python 3.12 is recommended.
```bash
cd backend
python3.12 -m venv .venv
source .venv/bin/activate
pip install -e ".[test,deepagents]"
uvicorn app.main:app --reload --host 127.0.0.1 --port 8010
```
Health check:
```bash
curl http://127.0.0.1:8010/api/health
```
### 3. Start Frontend
```bash
cd frontend
npm install
npm run dev
```
Access:
```text
http://127.0.0.1:5175
```
## Core Process
### Project Audit
```text
Upload project folder
↓
Click the "Code Review" button in the input box attachment area to explicitly initiate Project Audit
↓
Create review session
↓
Read uploaded files and generate initial review issues
↓
Issues enter issue pool
↓
User marks confirmed / false_positive / needs_review
↓
Click generate review report
↓
Structured report view
↓
Export JSON / Markdown
```
After uploading files, ordinary chat will not default to code review; only when you click the "Code Review" button or explicitly input "review / review / online risk / security vulnerability" and other intentions in the chat, it will enter Project Audit.
### Scheduler
```text
User naturally describes timed tasks in the unified chat box
↓
POST /api/schedules/plan
↓
Chat flow generates editable task confirmation card
↓
User can modify time, content, MCP tool, push channel
↓
User confirms card
↓
Save schedule to SQLite
↓
Top-right task drawer refresh
↓
Run now or background scheduler triggers at the point
↓
Call GitHub / Tavily / Feishu or WeCom
↓
Save run history
```
Feishu Webhook can be configured in `.env` with `FEISHU_WEBHOOK_URL`, or pasted and saved in the top-right `tool` drawer. Enterprise WeChat Webhook can still be configured through `WECOM_WEBHOOK_URL` or tool drawer. The page only displays desensitized addresses. If the selected Webhook is not configured, Run now will still generate results and tool logs, but the push status is false.
GitHub Explore brief main content prioritizes from GitHub API, displaying selected project cards, including project name, stars, language, highlights, suitable for whom, and GitHub direct link. Tavily is only used as a supplementary source and will not dump CSDN/blog and other search result texts into push content. Feishu push uses clean plain text and does not directly send Markdown report original text.
GitHub public read-only search does not require `GITHUB_TOKEN`; without token, it will use GitHub public API, which may be subject to stricter frequency limits. When deploying or using multiple users, configure GitHub OAuth App and let users click "Connect GitHub" in the tool drawer to complete authorization. The tool drawer will display GitHub rate limit and tool permission policy; read tools default `auto`, write tools default `confirm`, `disabled` will intercept at the backend execution level. Tavily requires `TAVILY_API_KEY`, and if not configured, it will display downgrade error in tool logs.
### MySQL Storage
Local default uses SQLite. Deployment can switch to MySQL:
```env
STORAGE_BACKEND=mysql
MYSQL_HOST=127.0.0.1
MYSQL_PORT=3306
MYSQL_USER=agent
MYSQL_PASSWORD=your-password
MYSQL_DATABASE=agent_console
```
MySQL store will automatically create the following business tables:
```text
schedules
schedule_runs
github_connections
github_oauth_states
audit_sessions
audit_messages
audit_issues
audit_reports
notification_channels
tool_permissions
tool_call_logs
```
```text
React Console
↓
Create/select session
↓
Upload file or folder
↓
POST /api/sessions/{session_id}/uploads
↓
DeepAgentDeps.upload_files(...)
↓
POST /api/chat/stream
↓
SessionStore retrieve message_history + deps
↓
slash command → <skill-hint> (optional soft prompt)
↓
Global Pydantic Deep Agent
↓
agent.iter(user_prompt, message_history, deps, conversation_id)
↓
SSE output status / token / tool_calls / tool_result / done
↓
Frontend render chat, execution status, tool logs, work tree
```
## Backend Design
### AgentFactory
`backend/app/core/agent_factory.py`
Create a global single Agent when the application starts. The Agent itself remains stateless, and specific session data is placed in `SessionStore`.
### PydanticDeepAgentsAdapter
`backend/app/core/deepagents_adapter.py`
Responsible for isolating `pydantic-deep` dependencies, mainly completing:
- import `pydantic_deep`
- construct DeepSeek provider/model
- call `create_deep_agent(...)`
- register `skill_directories`
- enable `include_skills=True`
- enable `include_filesystem=True`
- construct MCP toolset according to `backend/mcp_servers.json` and pass `mcp_servers`
- mount `SlidingWindowCapability`
- return clear error when failing, allowing fallback
### PydanticDeepAgentRunner
`backend/app/core/deepagents_runner.py`
Use `agent.iter(...)` instead of simple `run_stream(...)`, which can split the tool call process and send it to the frontend:
- `text`
- `tool_calls`
- `tool_result`
The frontend displays "reading file" and "searching content" based on this.
### SessionStore
`backend/app/core/session_store.py`
Each session saves:
- `messages`: pydantic-ai `ModelMessage` history
- `deps`: independent `DeepAgentDeps`
- `tool_logs`: tool and operation logs
The current implementation is in-memory storage, and the backend restart will lose.
### Uploads
`backend/app/api/uploads.py`
Upload files use independent multipart endpoint, no longer putting file content into chat JSON:
```text
POST /api/sessions/{session_id}/uploads
```
Backend write:
```python
session.deps.upload_files([(name, bytes), ...])
```
Agent subsequently reads through Pydantic Deep file tools:
```text
read_file
grep
glob
ls
```
## Frontend Design
The frontend is designed with a Codex-style workbench:
- Left side: collapsible session history
- Middle: chat flow, Agent status, and input box
- Right side: work tree and file preview, expandable/collapsible
- Bottom: running log summary
Key components:
```text
frontend/src/App.tsx
frontend/src/components/ConversationSidebar.tsx
frontend/src/components/ChatPanel.tsx
frontend/src/components/ui/animated-agent-input.tsx
frontend/src/components/ui/file-tree-preview.tsx
frontend/src/components/ui/file-preview.tsx
frontend/src/components/ui/agent-status-hint.tsx
```
When uploading folders, the frontend uses `webkitRelativePath` to preserve the directory structure, allowing the right-side work tree to expand by path.
## Skill Design
Skills use a standard directory structure:
```text
backend/skills/<skill-name>/SKILL.md
```
Currently built-in:
```text
code-review
test-generator
data-analysis
documentation-writer
```
These Skills are registered through Pydantic Deep `SkillsToolset`. Models can call autonomously:
```text
list_skills
load_skill
read_skill_resource
run_skill_script
```
Frontend commands are just soft hints:
| Command | Skill |
|---|---|
| `/review` | `code-review` |
| `/test` | `test-generator` |
| `/analyze` | `data-analysis` |
| `/docs` | `documentation-writer` |
| `/github` | Use GitHub MCP read-only tool |
## Prompt Design
`backend/app/core/prompts.py`
System prompts consist of two parts:
1. `pydantic_deep.BASE_PROMPT`
2. Project supplementary description
The project supplementary description is responsible for constraining:
- Default Chinese response
- Uploaded files in `/uploads`
- Use `read_file` / `grep` / `glob` to read uploaded files
- Do not claim to access the host machine workspace or Git repository
- If the user provides `<skill-hint>`, prioritize loading the corresponding Skill
Dynamic content is no longer manually spliced into the prompt. Skills, files, and history are managed by `SkillsToolset`, `DeepAgentDeps`, and `message_history`, respectively.
## Context Strategy
Currently, multi-turn context is managed by pydantic-ai `message_history`:
- Each round of requests passes the current session's `messages`
- Agent newly generated `ModelMessage` writes back to the session
- Tool calls and tool returns are also retained in history
- `SlidingWindowCapability(trigger=("tokens", 16000), keep=("tokens", 4000))` manages long context
Currently not enabled:
- `include_history_archive`
- `include_memory`
- Persistent message store
## MCP Configuration
Configuration file:
```text
backend/mcp_servers.json
```
Currently, it includes two entries by default:
- `mock-tools`: used for frontend status and tool list demonstration, not injected into the Agent's real MCP toolset.
- `github`: local stdio GitHub MCP Server, injected into Pydantic Deep Agent.
```json
{
"servers": [
{
"name": "mock-tools",
"transport": "stdio",
"command": "python",
"args": ["-m", "app.mcp.mock_server"],
"enabled": true
},
{
"name": "github",
"transport": "stdio",
"command": "python",
"args": ["-m", "app.mcp.github_server"],
"enabled": true
}
]
}
```
### GitHub MCP
`backend/app/mcp/github_server.py` implements a GitHub MCP Server, running on stdio and connected to the Agent through Pydantic AI MCP toolset. Read tools can be executed automatically, while write tools must go through the web console confirmation card.
Currently provides tools:
```text
github_get_repo
github_list_issues
github_get_issue
github_list_issue_comments
github_list_pull_requests
github_get_pull_request
github_list_pull_request_files
github_list_contents
github_get_file_content
github_list_commits
github_list_releases
github_list_workflow_runs
github_search_repositories
github_get_rate_limit
github_search_code
github_list_labels
github_list_branches
github_list_tags
github_list_contributors
github_list_projects
github_create_issue
github_comment_issue
github_add_labels
github_merge_pull_request
```
Public repository reads can be done without configuring a token, but the frequency limit is stricter. For local development, you can continue to use the `.env` bottom token:
```env
GITHUB_TOKEN=ghp_xxx
```
For online deployment, it is recommended not to let users manually configure tokens, but to create a GitHub OAuth App:
```text
Homepage URL: http://127.0.0.1:5175
Authorization callback URL: http://127.0.0.1:8010/api/github/oauth/callback
```
Then configure:
```env
GITHUB_CLIENT_ID=...
GITHUB_CLIENT_SECRET=...
GITHUB_OAUTH_REDIRECT_URL=http://127.0.0.1:8010/api/github/oauth/callback
FRONTEND_BASE_URL=http://127.0.0.1:5175
```
After the user clicks "Connect GitHub" in the top-right "Tool" drawer, the backend will save the user's connection through OAuth; GitHub MCP server will prioritize reading the OAuth token in SQLite/MySQL, and use the `GITHUB_TOKEN` to backfill if there is no connection. Creating issues, commenting, adding labels, and merging PRs require generating a confirmation card, which the user clicks to confirm before execution, and write to `tool_calls_logs`.
## API Overview
```text
GET /api/health
GET /api/skills
GET /api/mcp/servers
POST /api/mcp/reload
GET /api/mcp/permissions
PUT /api/mcp/permissions/{server_name}/{tool_name}
POST /api/mcp/actions/plan
POST /api/mcp/actions/confirm
GET /api/github/rate-limit
POST /api/sessions
POST /api/sessions/reset
GET /api/sessions/{session_id}
DELETE /api/sessions/{session_id}
POST /api/sessions/{session_id}/uploads
GET /api/sessions/{session_id}/files?path=/uploads/foo.py
POST /api/chat/stream
```
`/api/chat/stream` uses SSE:
```text
event: status
event: token
event: tool_calls
event: tool_result
event: done
event: error
```
## Testing
Backend testing:
```bash
cd backend
source .venv/bin/activate
pytest
```
Frontend build:
```bash
cd frontend
npm run build
```
Current test coverage:
- Skill discovery
- Slash commands and skill hints
- MCP configuration parsing
- GitHub MCP client read/write encapsulation
- GitHub MCP tool permissions, confirmation execution, and audit logs
- MCP toolset construction
- AgentFactory binding
- Pydantic Deep adapter parameters
- Pydantic Deep runner tool events
- DeepSeek SSE fallback parsing
- Session creation, reset, deletion, history
- Multipart upload
- File preview interface
## Known Limitations
- Sessions, uploaded files, and tool logs are all in memory and lost after backend restart.
- GitHub MCP has supported basic write operation confirmation links, but it is still not a complete GitHub App installation permission model; more fine-grained repository authorization, token encryption, permission audit query, and operation rollback guidance are needed before public deployment.
- GitHub OAuth token is currently saved in local SQLite, suitable for local demonstration; for public deployment, it should be changed to encrypted storage or access to cloud key management.
- The real MCP toolset currently uses `MCPServerStdio`, which has prompted future migration to the new version of `MCPToolset`.
- `mock-tools` is still for frontend demonstration/degradation purposes, not a standard MCP protocol service.
- File upload has no permission model, quota model, and virus/type verification.
- Folder upload quantity limit is on the frontend, and the backend does not have a more complete size and quantity limit.
- `SlidingWindowCapability` is a sliding window strategy and does not have summary memory and historical archiving.
- DeepSeek fallback only guarantees basic chat and does not have Pydantic Deep's Skill and file tool capabilities.
- Three.js background increases the first screen bundle volume.
## Follow-up Optimization Directions
### 1. Persistent Sessions and Files
Replace the current in-memory `SessionStore` with SQLite / Postgres + file system or object storage. This way, after the backend restarts, sessions, uploaded files, and tool logs can be recovered.
### 2. Extended MCP Capability
Currently, local stdio GitHub read-only MCP has been accessed. Follow-up can continue to extend:
```text
remote URL / SSE transport
GitHub OAuth
GitHub labels / projects / code search
tool permission policy
timeout and retry policy
tool result persistence
MCPToolset migration
```
### 3. Upload Security and Resource Limitations
Backend adds:
- Single file size limit
- Single session total capacity limit
- File quantity limit
- Binary file filtering
- MIME/extension verification
- Upload cleanup strategy
### 4. Stronger Context Management
Add outside the sliding window:
- History archive
- Summarization capability
- Session-level memory
- Project-level index
This way, long code library review will not rely solely on recent tokens.
### 5. Work Tree Experience Enhancement
The right-side work tree can continue to:
- Search files
- Expand/collapse all
- Display files read by Agent
- Display file read times
- Click tool logs to jump to the corresponding file
### 6. Tool Call Visualization
Upgrade the current light hint to a more complete execution trajectory:
- Current step
- List of files read
- Tools running
- Tool time consumption
- Error retry
### 7. Frontend Performance Optimization
- Three.js background dynamic import
- Large file tree virtual list
- Large message list virtual scrolling
- Token rendering batch processing
- Separate vendor chunks
### 8. Production Deployment
- Dockerfile / docker-compose
- Backend log structuring
- Frontend environment variable configuration
- Health check and readiness
- CI running pytest + npm build
MCP Config
Below is the configuration for this MCP Server. You can copy it directly to Cursor or other MCP clients.
mcp.json
Connection Info
You Might Also Like
No recommendations available