Aic MCP Agents

🤖 SAP MCP服务器——固定需求和GL预测代理

一个由AI驱动的MCP（模型上下文协议）服务器，用于连接 SAP S/4HANA 数据与a 大型语言模型（GPT-4o） 通过自然语言回答供应链查询和预测总账账户。

______________________________________________________________________

📖 目录

• 这个项目是做什么的？
• 这是给谁的？
• 简单解释关键概念
• 架构概述
• 按文件细分
• 数据流演练
• 三个暴露的工具
• 设置和配置
• 环境变量
• 如何跑步
• 示例查询
• 部署：本地与云铸造

______________________________________________________________________

🧐 这个项目是做什么的？

这个项目是 智能服务器 它位于人工智能助手（如SAP Joule）和SAP系统之间。它主要做三件事：

1. 回答供应链问题 --给定一个计划订单号或请购单号，它会自动从SAP获取相关的供需数据，并以整洁的表格形式返回。
2. 回答公司政策问题 --它使用RAG（人工智能知识库）系统，从内部文档中找到相关答案。
3. 预测总账账户 --给定财务文档的详细信息，它使用机器学习模型来建议向哪个总账账户过账。

把它看作是 聪明的中间人 -它需要一个简单的英语问题，找出要调用的SAP API，调用它，并给出一个干净、格式化的答案。

______________________________________________________________________

👥 这是给谁的？

• SAP顾问 构建人工智能辅助的工作流程
• 开发者 将LLM与企业ERP系统集成
• 业务分析师 谁想了解人工智能如何连接到SAP数据
• 初学者 好奇现实世界中的人工智能代理在生产中是如何工作的

不需要有Python经验 *理解* 这个README。基本的熟悉度有助于 *跑* 它

______________________________________________________________________

🧱 简单解释关键概念

在深入探讨之前，这里有一个你会遇到的快速术语表：

______________________________________________________________________

🏗 架构概述

┌─────────────────────────────────────────────────────────────────┐
│                        AI Assistant                              │
│                    (e.g. SAP Joule / Claude)                    │
└─────────────────────────┬───────────────────────────────────────┘
                          │  Sends natural language query
                          ▼
┌─────────────────────────────────────────────────────────────────┐
│                     MCP Server  (main.py)                        │
│                                                                  │
│   Exposes 3 tools over HTTP:                                     │
│   ┌──────────────────┐ ┌───────────────────┐ ┌───────────────┐  │
│   │  echo()          │ │get_company_       │ │get_gl_        │  │
│   │  (Agent Tool)    │ │policies()         │ │prediction()   │  │
│   └────────┬─────────┘ └────────┬──────────┘ └──────┬────────┘  │
└────────────┼────────────────────┼───────────────────┼───────────┘
             │                    │                   │
             ▼                    ▼                   ▼
┌────────────────────┐  ┌─────────────────┐  ┌────────────────────┐
│   Agent (agent.py) │  │  RAG API        │  │  SAP DAR           │
│                    │  │  (resource.py)  │  │  ML Service        │
│  GPT-4o (via       │  │                 │  │  (tools.py)        │
│  Gen AI Hub)       │  │  External       │  │                    │
│        +           │  │  HTTP endpoint  │  │  Predicts GL       │
│  3 MRP Tools       │  │                 │  │  account           │
└────────┬───────────┘  └─────────────────┘  └────────────────────┘
         │
         │  Calls the right tool based on input type
         ▼
┌─────────────────────────────────────────────────────────────────┐
│                     SAP S/4HANA APIs  (tools.py)                │
│                                                                  │
│  ┌────────────────────────┐   ┌──────────────────────────────┐  │
│  │ Planned Order API      │   │ Purchase Requisition API     │  │
│  │ /api_plannedorder/...  │   │ /api_purchaserequisition_2/  │  │
│  └────────────┬───────────┘   └─────────────┬────────────────┘  │
│               │                             │                    │
│               └──────────────┬──────────────┘                   │
│                              ▼                                   │
│              ┌───────────────────────────────┐                  │
│              │  Pegged Requirements API      │                  │
│              │  /zmm_sb_joule_pegged/...     │                  │
│              └───────────────────────────────┘                  │
└─────────────────────────────────────────────────────────────────┘

简单来说：

1. AI助手向此服务器发送问题
2. 服务器将其路由到正确的“工具”（功能）
3. 该工具调用SAP API以获取真实数据
4. AI将数据格式化为干净的Markdown表
5. 答案将返回给用户

______________________________________________________________________

📁 按文件细分

project/
│
├── main.py        ← Entry point: starts the server, registers tools
├── agent.py       ← AI brain: GPT-4o + tool selection logic
├── tools.py       ← SAP API callers + GL prediction
├── resource.py    ← RAG system connector
├── config.py      ← Configuration & secrets loader
├── env.example    ← Template showing what secrets are needed
└── README.md      ← This file

______________________________________________________________________

main.py --服务器入口点

它的作用： 启动HTTP服务器并注册三个可调用的“工具”，AI助手可以调用这些工具。

将此视为 前门 的应用程序。当人工智能助手想要做某事时，它会敲门并要求三种服务中的一种。

main.py registers:
├── echo()               → Routes to the AI Agent (for MRP/pegged requirements)
├── get_company_policies() → Routes to the RAG system (for policy questions)
└── get_gl_prediction()  → Routes to the DAR ML model (for GL account prediction)

服务器在端口上运行 8000 默认情况下（可通过配置 PORT 环境变量）并监听所有网络接口(0.0.0.0).

______________________________________________________________________

agent.py --AI大脑

它的作用： 创建一个由GPT-4o支持的AI代理，该代理读取用户查询，决定调用哪个SAP工具，并返回一个格式化的Markdown表。

这是系统中最“智能”的部分。以下是逐步发生的事情：

User query arrives
       │
       ▼
GPT-4o reads the query + system prompt
       │
       ├── Is it a Planned Order number?     → calls get_mrp_plannedorder()
       ├── Is it a Purchase Req number?      → calls get_mrp_purchaserequisition()
       └── Is it Material + Area + Plant?    → calls get_pegged_requirements_for_mrp2()
       │
       ▼
Tool returns raw SAP data (a list of records)
       │
       ▼
GPT-4o formats it into a Markdown table
       │
       ▼
Table is returned as a string

这 系统提示 (agent_instruction)是一组用通俗英语编写的指令，告诉GPT-4o具体如何操作——选择哪种工具，如何格式化输出，以及遵循什么规则。

______________________________________________________________________

tools.py -SAP API调用方

它的作用： 包含通过HTTP REST API与SAP S/4HANA实际通信的所有函数。还包含GL预测功能。

有 5功能 在这里：

SAP API调用的工作方式如下：

# 1. Build URL
URL = BASE_URL + "api_plannedorder/.../400000285"

# 2. Send HTTP GET with username + password
response = requests.get(url=URL, auth=(USER, PASSWORD))

# 3. Decode the response bytes to text
data_str = response.content.decode("utf-8")

# 4. Parse JSON text into a Python dictionary
data = json.loads(data_str)

# 5. Extract what you need
material = data.get("Material")

______________________________________________________________________

resource.py --RAG系统连接器

它的作用： 将问题发送到外部RAG（AI知识库）API并返回答案。

RAG的工作原理如下：

User question
     │
     ▼
RAG API searches internal documents
     │
     ▼
Finds the most relevant document chunks
     │
     ▼
LLM generates an answer based on those chunks
     │
     ▼
Answer returned to user

该函数只是发送一个HTTP GET请求，并将查询作为URL参数(?message=your_question)并返回 response JSON回复中的字段。

______________________________________________________________________

config.py --配置加载器

它的作用： 以安全、结构化的方式加载所有机密和配置值——从 .env 本地文件或生产中的Cloud Foundry服务绑定。

这是一种安全最佳实践： 永远不要在代码中硬编码密码。相反，在运行时从环境中读取它们。

Is the app running in Cloud Foundry?
        │
        ├── YES → Read from CF service bindings (VCAP_SERVICES)
        │         └── Extract AI Core credentials automatically
        │
        └── NO  → Read from local .env file
                  └── You fill this in yourself for development

这 Settings 类使用 派丹蒂克 （Python库）来准确定义预期的变量及其类型。这可以及早发现拼写错误和缺失的值。

______________________________________________________________________

env.example --机密模板

它的作用： 向您准确显示需要提供的秘密，而不会透露任何实际价值。

DAR_DEPLOYMENT_URL = ""    ← URL of your deployed DAR ML model
DAR_BASE_URL = ""          ← Base URL of SAP DAR service
DAR_CLIENT_ID = ""         ← OAuth client ID for DAR
DAR_CLIENT_SECRET = ""     ← OAuth client secret for DAR
DAR_AUTH_URL = ""          ← Auth URL for DAR

RAG_ENDPOINT = ""          ← URL of your RAG API

BASE_URL = ""              ← Your SAP S/4HANA base URL
USER = ""                  ← SAP username
PASSWORD = ""              ← SAP password

将此文件复制到 .env 并填写您的实际值。

______________________________________________________________________

🔄 数据流演练

场景1：用户询问计划订单

User: "Give me pegged requirements for Planned Order 400000285"

1. MCP Server (main.py) receives query → calls echo()
2. echo() passes query to agent() in agent.py
3. GPT-4o reads the query, sees a Planned Order number
4. GPT-4o calls get_mrp_plannedorder("400000285")
5. tools.py hits SAP API:
   GET /api_plannedorder/.../400000285
   → Returns: Material="MAT001", Plant="1810", MRPArea="1810"
6. tools.py calls get_pegged_requirements_for_mrp2("MAT001","1810","1810","400000285")
7. SAP returns a list of pegged requirement records
8. GPT-4o formats the records into a Markdown table:

   | Material | PR_PlannedOrder | Assembly | AssemblyPR_PlannedOrder |
   |----------|-----------------|----------|--------------------------|
   | MAT001   | 400000285       | ASSY001  | 500000123               |

9. Table is returned to the AI assistant

场景2：用户提出政策问题

User: "What is the policy for vendor payment terms?"

1. MCP Server receives query → calls get_company_policies()
2. resource.py sends GET request to RAG_ENDPOINT?message=...
3. RAG system searches internal policy documents
4. Returns AI-generated answer based on found documents
5. Answer is returned to user

场景3：总账账户预测

User (or system): Provides financial document fields

1. MCP Server receives fields → calls get_gl_prediction()
2. tools.py creates an inference request with all fields
3. SAP DAR ML model processes the fields
4. Returns top 3 GL account predictions with confidence scores
5. Results returned to caller

______________________________________________________________________

🛠 三个暴露的工具

AI助手可以通过MCP调用以下三个功能：

1. echo(query: str) → str

• 目的： 处理MRP/供应链查询
• 输入： 包含订单号、请购单号或材料+区域+工厂的自然语言问题
• 输出： 固定需求Markdown表
• 内部使用： agent.py → GPT-4o→ SAP API

2. get_company_policies(query: str) → str

• 目的： 回答有关公司内部政策的问题
• 输入： 一个自然语言问题
• 输出： 来自RAG知识库的AI生成答案
• 内部使用： resource.py → 外部RAG API

3. get_gl_prediction(Company_Code, Document_Number, Fiscal_Year, LineItem, AccountType, Amount, Vendor, DocumentType, PostingDate, TaxCode)

• 目的： 预测财务文档的正确总账科目
• 输入： 10个财务文档字段（全部为字符串）
• 输出： 总账账户预测前三名
• 内部使用： tools.py → SAP DAR ML服务

______________________________________________________________________

⚙️ 设置和配置

先决条件

确保已安装以下内容：

• Python 3.9或更高版本
• pip （Python包管理器）
• 访问SAP S/4HANA系统
• 访问SAP Gen AI Hub（适用于GPT-4o）
• 访问SAP DAR服务（用于总账预测）
• 正在运行的RAG端点

安装

# 1. Clone the repository
git clone 
cd 

# 2. Create a virtual environment (keeps dependencies isolated)
python -m venv venv

# 3. Activate the virtual environment
# On Mac/Linux:
source venv/bin/activate
# On Windows:
venv\Scripts\activate

# 4. Install dependencies
pip install -r requirements.txt

关键依赖

______________________________________________________________________

🔐 环境变量

复制 env.example 到名为的新文件 .env:

cp env.example .env

然后填写您的实际值：

# SAP DAR (Data Attribute Recommendation) — for GL prediction
DAR_DEPLOYMENT_URL = "https://your-dar-deployment-url"
DAR_BASE_URL = "https://your-dar-base-url"
DAR_CLIENT_ID = "your-client-id"
DAR_CLIENT_SECRET = "your-client-secret"
DAR_AUTH_URL = "https://your-auth-url"

# RAG System — for company policy queries
RAG_ENDPOINT = "https://your-rag-api-endpoint"

# SAP S/4HANA — for MRP/supply chain data
BASE_URL = "https://your-s4hana-url/"
USER = "your-sap-username"
PASSWORD = "your-sap-password"

⚠️ 永远不要承诺你的 .env 文件到Git。 添加到 .gitignore.

______________________________________________________________________

🚀 如何跑步

本地开发

# Make sure your .env file is filled in
python main.py

服务器将在以下时间启动： http://localhost:8000

您可以通过设置来更改端口 PORT 环境变量：

PORT=9000 python main.py

验证它是否正在运行

MCP服务器公开一个HTTP端点。您可以通过访问来检查它是否存活：

http://localhost:8000

______________________________________________________________________

💬 示例查询

以下是服务器连接到AI助手后如何查询每个工具：

按计划订单列出的要求：

“显示计划订单400000285的挂钩需求”

按请购单列出的要求：

“获取采购申请3000001516的固定要求”

按材料细节列出的栓接要求：

“在工厂1810和MRP区域1810中获取物料KKR001的挂钩要求”

公司政策：

“我们对三方发票匹配的政策是什么？”

GL预测：

*（以编程方式发送，包含所有10个财务字段）*

______________________________________________________________________

☁️ 部署：本地与云铸造

这 config.py 文件会自动处理两种环境：

本地开发

• 从您的数据库中读取所有配置 .env 文件
• DEBUG=True 默认情况下
• 除了填写外，不需要额外的设置 .env

Cloud Foundry（SAP BTP）

• 发现 VCAP_SERVICES 环境变量自动
• 从绑定服务读取AI Core凭据
• 从CF环境变量中读取所有其他配置
• DEBUG=False 自动投入生产

要在Cloud Foundry上部署：

cf push

确保你的 manifest.yml 包括环境变量和AI核心服务绑定。

______________________________________________________________________

🔍 人工智能如何决定调用哪个工具

这就是魔法 代理系统提示(agent_instruction 在 agent.py)为GPT-4o提供了一套明确的规则：

IF input looks like a Planned Order number  → use get_mrp_plannedorder
IF input looks like a Purchase Req number   → use get_mrp_purchaserequisition  
IF input has Material + Area + Plant        → use get_pegged_requirements_for_mrp

GPT-4o读取您的查询，应用这些规则，调用正确的函数，接收原始数据，然后将其转换为所需的表格式——所有这些都是自动的。