Invoice Management MCP

发票管理系统

使用Go和Next.js构建的全面发票管理系统，具有人工智能搜索和模型上下文协议（MCP）集成功能。

特性

• 📄 发票管理：创建、读取、更新和删除包含详细行项目的发票
• 🏢 公司和接收人管理：组织供应商和发票接收人
• 🏷️ 类别和标签：灵活的分类和标记系统
• 📊 分析和报告：内置分析和统计仪表板
• 📤 文件上传：用于发票附件的S3兼容存储
• 🔍 人工智能驱动的搜索：使用AI SDK的智能搜索功能
• 🤖 MCP 服务器：AI助手的模型上下文协议集成
• 💱 货币支持：可进行汇率转换的多种货币
• 🔐 OAuth身份验证：使用JWT令牌进行安全身份验证
• 📱 响应式用户界面：现代Next.js前端，支持移动端

技术栈

后端

• 转到1.25+：主要后端语言
• 光纤v2：快速HTTP框架
• GORM：ORM用于数据库操作
• 语言/SQLite：数据库（支持本地SQLite和Turso）
• AWS SDK v2：S3兼容存储集成
• MCP Go：模型上下文协议服务器实现
• OpenAPI 3.0：API规范和代码生成

前端

• Next.js 16：React框架
• TypeScript：类型安全开发
• TanStack 查询：数据获取和缓存
• TanStack表：高级表格组件
• Shadcn UI：组件库
• Tailwind CSS：实用性优先的造型
• React钩子形式：使用Zod验证进行表单管理
• 重新图表：数据可视化
• AI SDK：AI驱动的功能

入门指南

先决条件

• 达到1.25或更高
• Node.js 20或更高版本
• Docker和Docker Compose（可选）
• Bun或npm包管理器

环境变量

创建一个 .env 根目录中的文件，包含以下变量：

# Server
PORT=8080

# Database (Turso) - Leave empty to use local SQLite
TURSO_DATABASE_URL=
TURSO_AUTH_TOKEN=

# S3-compatible storage
S3_ENDPOINT=your-s3-endpoint
S3_BUCKET=your-bucket-name
S3_ACCESS_KEY=your-access-key
S3_SECRET_KEY=your-secret-key
S3_REGION=us-east-1
S3_USE_PATH_STYLE=false

# Authentication
MCPROUTER_SERVER_URL=your-mcprouter-url
MCPROUTER_SERVER_API_KEY=your-api-key
OAUTH_SERVER_URL=your-oauth-server
OAUTH_ISSUER=your-oauth-issuer
OAUTH_AUDIENCE=your-oauth-audience

# File Server (for unlinking files)
FILE_SERVER_URL=your-file-server-url

安装

选项1：使用Docker Compose（推荐）

# Start the application
docker-compose up -d

# View logs
docker-compose logs -f

# Stop the application
docker-compose down

方案2：地方发展

后端：

# Install dependencies
make deps

# Generate OpenAPI code
make generate

# Build the binary
make build

# Run the server
make run

# Or run with hot reload (requires air)
air

前端：

cd frontend

# Install dependencies
bun install

# Run development server
bun dev

# Build for production
bun build

开发命令

后端：

make deps           # Download and tidy dependencies
make build          # Build the binary
make run            # Run the server
make test           # Run tests
make test-e2e       # Run E2E tests
make test-coverage  # Run tests with coverage
make fmt            # Format code
make lint           # Lint code
make generate       # Generate OpenAPI code
make clean          # Clean build artifacts
make install-local  # Install binary to /usr/local/bin

前端：

bun dev     # Start development server
bun build   # Build for production
bun start   # Start production server
bun lint    # Run ESLint

项目结构

.
├── cmd/
│   └── server/          # Main application entry point
├── internal/
│   ├── api/             # API server and handlers
│   │   ├── handlers/    # HTTP request handlers
│   │   ├── middleware/  # Middleware functions
│   │   └── generated/   # OpenAPI generated code
│   ├── assets/          # Static assets and OpenAPI spec
│   ├── mcp/             # Model Context Protocol server
│   ├── models/          # Database models
│   ├── services/        # Business logic services
│   ├── tools/           # MCP tools implementation
│   └── utils/           # Utility functions
├── frontend/            # Next.js frontend application
│   ├── app/             # Next.js app directory
│   │   ├── (auth)/      # Authentication pages
│   │   ├── (dashboard)/ # Dashboard pages
│   │   └── api/         # API routes
│   ├── components/      # React components
│   ├── hooks/           # Custom React hooks
│   └── lib/             # Utility libraries and API clients
├── e2e/                 # End-to-end tests
├── k8s/                 # Kubernetes deployment configs
└── oapi-codegen/        # OpenAPI code generation configs

API 文档

API遵循OpenAPI 3.0规范。关键端点包括：

• /api/health -健康检查
• /api/categories -品类管理
• /api/companies -公司/供应商管理
• /api/receivers -发票接收人管理
• /api/tags -标签管理
• /api/invoices -发票CRUD操作
• /api/invoices/{id}/items -发票行项目
• /api/upload -文件上传操作
• /api/analytics/* -分析和统计

API完整文档可在 内部/资产/openapi.yaml.

MCP 服务器

该项目包括一个模型上下文协议（MCP）服务器，允许AI助手与发票管理系统进行交互。MCP服务器提供以下工具：

• 创建、读取、更新和删除发票
• 管理类别、公司、接收者和标签
• 上传和管理文件
• 生成分析和统计数据

MCP服务器与主API服务器一起自动启动。

Kubernetes部署

Kubernetes部署配置可在 k8s/ 目录：

cd k8s

# Apply all configurations
kubectl apply -k .

# Or apply individually
kubectl apply -f namespace.yaml
kubectl apply -f secrets.yaml
kubectl apply -f deployment.yaml
kubectl apply -f service.yaml
kubectl apply -f ingress.yaml
kubectl apply -f cluster-issuer.yaml

看 k8s/README.md 了解详细的部署说明。

测试

单元测试：

make test

E2E API试验：

make test-e2e

保险范围报告：

make test-coverage

贡献

1. 分叉存储库
2. 创建要素分支(git checkout -b feature/amazing-feature)
3. 提交您的更改(git commit -m 'Add some amazing feature')
4. 推到分支(git push origin feature/amazing-feature)
5. 打开拉取请求

许可证

该项目由以下人员维护 RxTech实验室.

支持

有关问题和疑问，请在GitHub上打开问题。

致谢

• 建于 纤维
• 前端由以下设备供电 Next.js
• UI组件来自 Shadcn UI
• MCP集成通过 mcp走