Skip to content

Commit 93e684c

Browse files
actions-useractions-user
committed
docs: update codeboarding documentation and generate architecture
## 📚 Documentation Update This commit contains updated documentation files fetched from the CodeBoarding service and automatically generated architecture documentation. ### 📊 Summary - Documentation files created/updated: 7 - JSON files created/updated: 8 - Documentation directory: .codeboarding/ - JSON directory: .codeboarding/ - Output format: .mdx - Repository analyzed: https://github.com/mcp-use/mcp-use - Architecture documentation: docs/development/architecture.mdx (auto-generated) The generated .mdx files have been automatically appended to the development documentation, and the architecture.mdx file has been generated from the CodeBoarding analysis files. 🤖 This commit was automatically generated by the CodeBoarding documentation update workflow.
1 parent 9776a2a commit 93e684c

18 files changed

+1538
-637
lines changed

‎.codeboarding/Agent_Orchestration_Core.json‎

Lines changed: 163 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,163 @@
1+
{
2+
"description": "The `mcp-use` agent subsystem is designed around a central `Agent Core` that orchestrates interactions with various components to achieve its goals. It leverages a `Prompt Construction` module to dynamically generate context-rich prompts for the `LLM Interface`, which abstracts communication with large language models. For executing specific tasks, the `Agent Core` delegates to a `Tool Executor`, which manages the invocation of external capabilities. The `Conversational State Manager`, an intrinsic part of the `Agent Core`, maintains the dialogue history and context, ensuring coherent interactions. Additionally, a `Remote Execution Handler` allows the agent to offload tasks to remote MCP servers, extending its operational reach. This architecture emphasizes modularity, allowing for flexible integration of different LLMs and tools while maintaining a clear separation of concerns.",
3+
"components": [
4+
{
5+
"name": "Agent Core",
6+
"description": "The primary orchestrator and decision-making unit of the agent. It manages the overall flow, interprets LLM outputs, and decides on subsequent actions, including tool usage or further LLM interactions. It also encapsulates the conversational state management.",
7+
"referenced_source_code": [
8+
{
9+
"qualified_name": "mcp_use.agents.mcpagent.MCPAgent",
10+
"reference_file": "mcp_use/agents/mcpagent.py",
11+
"reference_start_line": 48,
12+
"reference_end_line": 1145
13+
},
14+
{
15+
"qualified_name": "mcp_use.agents.base.BaseAgent",
16+
"reference_file": "mcp_use/agents/base.py",
17+
"reference_start_line": 13,
18+
"reference_end_line": 61
19+
}
20+
],
21+
"assigned_files": [
22+
"mcp_use/agents/base.py",
23+
"mcp_use/agents/mcpagent.py"
24+
],
25+
"can_expand": true
26+
},
27+
{
28+
"name": "Prompt Construction",
29+
"description": "Responsible for dynamically generating and formatting prompts for the LLM, incorporating conversational context, available tools, and specific instructions to guide the LLM's behavior.",
30+
"referenced_source_code": [
31+
{
32+
"qualified_name": "mcp_use.agents.prompts.system_prompt_builder.create_system_message",
33+
"reference_file": "mcp_use/agents/prompts/system_prompt_builder.py",
34+
"reference_start_line": 59,
35+
"reference_end_line": 103
36+
}
37+
],
38+
"assigned_files": [
39+
"mcp_use/agents/prompts/system_prompt_builder.py"
40+
],
41+
"can_expand": false
42+
},
43+
{
44+
"name": "Remote Execution Handler",
45+
"description": "Manages the delegation and execution of tasks or tool calls on remote MCP (Multi-Component Platform) servers, handling the communication protocol and result retrieval.",
46+
"referenced_source_code": [
47+
{
48+
"qualified_name": "mcp_use.agents.remote.RemoteAgent",
49+
"reference_file": "mcp_use/agents/remote.py",
50+
"reference_start_line": 34,
51+
"reference_end_line": 327
52+
}
53+
],
54+
"assigned_files": [
55+
"mcp_use/agents/remote.py"
56+
],
57+
"can_expand": true
58+
},
59+
{
60+
"name": "LLM Interface",
61+
"description": "Provides a standardized abstraction layer for interacting with various Large Language Models, handling request formatting, sending prompts, and parsing responses.",
62+
"referenced_source_code": [
63+
{
64+
"qualified_name": "langchain_core.language_models.BaseLanguageModel",
65+
"reference_file": "full/path/to/file.txt",
66+
"reference_start_line": 10,
67+
"reference_end_line": 25
68+
}
69+
],
70+
"assigned_files": [],
71+
"can_expand": true
72+
},
73+
{
74+
"name": "Tool Executor",
75+
"description": "Manages the invocation and execution of external tools or internal functions that the agent decides to use to achieve its goals. It handles tool input, execution, and output processing.",
76+
"referenced_source_code": [
77+
{
78+
"qualified_name": "langchain.agents.AgentExecutor",
79+
"reference_file": "",
80+
"reference_start_line": null,
81+
"reference_end_line": null
82+
}
83+
],
84+
"assigned_files": [],
85+
"can_expand": false
86+
},
87+
{
88+
"name": "Conversational State Manager",
89+
"description": "Responsible for maintaining and updating the ongoing conversational context, including message history, user inputs, and agent thoughts, ensuring coherent and context-aware interactions. This functionality is integrated within the `Agent Core`.",
90+
"referenced_source_code": [
91+
{
92+
"qualified_name": "mcp_use.agents.mcpagent.MCPAgent",
93+
"reference_file": "mcp_use/agents/mcpagent.py",
94+
"reference_start_line": 48,
95+
"reference_end_line": 1145
96+
}
97+
],
98+
"assigned_files": [],
99+
"can_expand": true
100+
},
101+
{
102+
"name": "Unclassified",
103+
"description": "Component for all unclassified files and utility functions (Utility functions/External Libraries/Dependencies)",
104+
"referenced_source_code": [],
105+
"assigned_files": [
106+
"mcp_use/agents/prompts/templates.py"
107+
],
108+
"can_expand": false
109+
}
110+
],
111+
"components_relations": [
112+
{
113+
"relation": "Uses",
114+
"src_name": "Agent Core",
115+
"dst_name": "Prompt Construction"
116+
},
117+
{
118+
"relation": "Provides prompts to",
119+
"src_name": "Prompt Construction",
120+
"dst_name": "Agent Core"
121+
},
122+
{
123+
"relation": "Communicates with",
124+
"src_name": "Agent Core",
125+
"dst_name": "LLM Interface"
126+
},
127+
{
128+
"relation": "Sends responses to",
129+
"src_name": "LLM Interface",
130+
"dst_name": "Agent Core"
131+
},
132+
{
133+
"relation": "Delegates to",
134+
"src_name": "Agent Core",
135+
"dst_name": "Tool Executor"
136+
},
137+
{
138+
"relation": "Returns execution results to",
139+
"src_name": "Tool Executor",
140+
"dst_name": "Agent Core"
141+
},
142+
{
143+
"relation": "Manages",
144+
"src_name": "Agent Core",
145+
"dst_name": "Conversational State Manager"
146+
},
147+
{
148+
"relation": "Provides and updates state for",
149+
"src_name": "Conversational State Manager",
150+
"dst_name": "Agent Core"
151+
},
152+
{
153+
"relation": "Initiates tasks via",
154+
"src_name": "Agent Core",
155+
"dst_name": "Remote Execution Handler"
156+
},
157+
{
158+
"relation": "Returns results to",
159+
"src_name": "Remote Execution Handler",
160+
"dst_name": "Agent Core"
161+
}
162+
]
163+
}

‎.codeboarding/Agent_Orchestration_Core.mdx‎

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
# Agent Orchestration Core
2+
```mermaid
3+
graph LR
4+
Agent_Core["Agent Core"]
5+
Prompt_Construction["Prompt Construction"]
6+
Remote_Execution_Handler["Remote Execution Handler"]
7+
LLM_Interface["LLM Interface"]
8+
Tool_Executor["Tool Executor"]
9+
Conversational_State_Manager["Conversational State Manager"]
10+
Unclassified["Unclassified"]
11+
Agent_Core -- "Uses" --> Prompt_Construction
12+
Prompt_Construction -- "Provides prompts to" --> Agent_Core
13+
Agent_Core -- "Communicates with" --> LLM_Interface
14+
LLM_Interface -- "Sends responses to" --> Agent_Core
15+
Agent_Core -- "Delegates to" --> Tool_Executor
16+
Tool_Executor -- "Returns execution results to" --> Agent_Core
17+
Agent_Core -- "Manages" --> Conversational_State_Manager
18+
Conversational_State_Manager -- "Provides and updates state for" --> Agent_Core
19+
Agent_Core -- "Initiates tasks via" --> Remote_Execution_Handler
20+
Remote_Execution_Handler -- "Returns results to" --> Agent_Core
21+
```
22+
23+
### Details
24+
25+
The `mcp-use` agent subsystem is designed around a central `Agent Core` that orchestrates interactions with various components to achieve its goals. It leverages a `Prompt Construction` module to dynamically generate context-rich prompts for the `LLM Interface`, which abstracts communication with large language models. For executing specific tasks, the `Agent Core` delegates to a `Tool Executor`, which manages the invocation of external capabilities. The `Conversational State Manager`, an intrinsic part of the `Agent Core`, maintains the dialogue history and context, ensuring coherent interactions. Additionally, a `Remote Execution Handler` allows the agent to offload tasks to remote MCP servers, extending its operational reach. This architecture emphasizes modularity, allowing for flexible integration of different LLMs and tools while maintaining a clear separation of concerns.
26+
27+
### Agent Core
28+
The primary orchestrator and decision-making unit of the agent. It manages the overall flow, interprets LLM outputs, and decides on subsequent actions, including tool usage or further LLM interactions. It also encapsulates the conversational state management.
29+
30+
31+
**Related Classes/Methods**:
32+
33+
- <a href="https://github.com/mcp-use/mcp-use/blob/main/mcp_use/agents/mcpagent.py#L48-L1145" target="_blank" rel="noopener noreferrer">QName:`mcp_use.agents.mcpagent.MCPAgent` FileRef: `mcp_use/agents/mcpagent.py`, Lines:(48:1145)</a>
34+
- <a href="https://github.com/mcp-use/mcp-use/blob/main/mcp_use/agents/base.py#L13-L61" target="_blank" rel="noopener noreferrer">QName:`mcp_use.agents.base.BaseAgent` FileRef: `mcp_use/agents/base.py`, Lines:(13:61)</a>
35+
36+
37+
### Prompt Construction
38+
Responsible for dynamically generating and formatting prompts for the LLM, incorporating conversational context, available tools, and specific instructions to guide the LLM's behavior.
39+
40+
41+
**Related Classes/Methods**:
42+
43+
- <a href="https://github.com/mcp-use/mcp-use/blob/main/mcp_use/agents/prompts/system_prompt_builder.py#L59-L103" target="_blank" rel="noopener noreferrer">QName:`mcp_use.agents.prompts.system_prompt_builder.create_system_message` FileRef: `mcp_use/agents/prompts/system_prompt_builder.py`, Lines:(59:103)</a>
44+
45+
46+
### Remote Execution Handler
47+
Manages the delegation and execution of tasks or tool calls on remote MCP (Multi-Component Platform) servers, handling the communication protocol and result retrieval.
48+
49+
50+
**Related Classes/Methods**:
51+
52+
- <a href="https://github.com/mcp-use/mcp-use/blob/main/mcp_use/agents/remote.py#L34-L327" target="_blank" rel="noopener noreferrer">QName:`mcp_use.agents.remote.RemoteAgent` FileRef: `mcp_use/agents/remote.py`, Lines:(34:327)</a>
53+
54+
55+
### LLM Interface
56+
Provides a standardized abstraction layer for interacting with various Large Language Models, handling request formatting, sending prompts, and parsing responses.
57+
58+
59+
**Related Classes/Methods**:
60+
61+
- <a href="https://github.com/mcp-use/mcp-use/blob/main/full/path/to/file.txt#L10-L25" target="_blank" rel="noopener noreferrer">QName:`langchain_core.language_models.BaseLanguageModel` FileRef: `full/path/to/file.txt`, Lines:(10:25)</a>
62+
63+
64+
### Tool Executor
65+
Manages the invocation and execution of external tools or internal functions that the agent decides to use to achieve its goals. It handles tool input, execution, and output processing.
66+
67+
68+
**Related Classes/Methods**:
69+
70+
- QName:`langchain.agents.AgentExecutor` FileRef: ``
71+
72+
73+
### Conversational State Manager
74+
Responsible for maintaining and updating the ongoing conversational context, including message history, user inputs, and agent thoughts, ensuring coherent and context-aware interactions. This functionality is integrated within the `Agent Core`.
75+
76+
77+
**Related Classes/Methods**:
78+
79+
- <a href="https://github.com/mcp-use/mcp-use/blob/main/mcp_use/agents/mcpagent.py#L48-L1145" target="_blank" rel="noopener noreferrer">QName:`mcp_use.agents.mcpagent.MCPAgent` FileRef: `mcp_use/agents/mcpagent.py`, Lines:(48:1145)</a>
80+
81+
82+
### Unclassified
83+
Component for all unclassified files and utility functions (Utility functions/External Libraries/Dependencies)
84+
85+
86+
**Related Classes/Methods**: _None_

‎.codeboarding/Authentication_Service.json‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
{
2+
"description": "The authentication subsystem in `mcp_use.auth` is designed to handle OAuth 2.0 authentication flows and apply bearer tokens to outgoing HTTP requests. The `OAuth Handler` component, implemented by the `mcp_use.auth.oauth.OAuth` class, is responsible for orchestrating the OAuth process, including discovering server capabilities, dynamic client registration, and managing token storage. Once access tokens are acquired, the `Bearer Token Manager` component, implemented by `mcp_use.auth.bearer.BearerAuth`, takes these tokens and applies them as `Authorization: Bearer` headers to `External HTTP Requests`. This ensures secure communication with external services, such as MCP servers. The `OAuth Handler` provides the necessary access tokens to the `Bearer Token Manager`, which then uses them to authenticate `External HTTP Requests`.",
3+
"components": [
4+
{
5+
"name": "OAuth Handler",
6+
"description": "Manages the entire OAuth 2.0 protocol flow. This includes initiating authentication requests with external OAuth providers, handling redirects, and securely obtaining and storing access tokens. It acts as the primary interface for acquiring the necessary authentication credentials.",
7+
"referenced_source_code": [
8+
{
9+
"qualified_name": "mcp_use.auth.oauth.OAuth",
10+
"reference_file": "mcp_use/auth/oauth.py",
11+
"reference_start_line": 167,
12+
"reference_end_line": 625
13+
}
14+
],
15+
"assigned_files": [
16+
"mcp_use/auth/oauth.py",
17+
"mcp_use/auth/oauth_callback.py"
18+
],
19+
"can_expand": true
20+
},
21+
{
22+
"name": "Bearer Token Manager",
23+
"description": "Responsible for taking an acquired access token (typically from the OAuth Handler) and correctly formatting it as a bearer token. It then integrates this token into the Authorization header of outgoing HTTP requests, ensuring secure and authenticated communication with MCP servers.",
24+
"referenced_source_code": [
25+
{
26+
"qualified_name": "mcp_use.auth.bearer.BearerAuth",
27+
"reference_file": "mcp_use/auth/bearer.py",
28+
"reference_start_line": 9,
29+
"reference_end_line": 17
30+
}
31+
],
32+
"assigned_files": [
33+
"mcp_use/auth/bearer.py"
34+
],
35+
"can_expand": false
36+
},
37+
{
38+
"name": "External HTTP Requests",
39+
"description": "Represents any HTTP requests made to external services or APIs, typically to MCP servers, that require authentication.",
40+
"referenced_source_code": [
41+
{
42+
"qualified_name": "requests.request",
43+
"reference_file": "",
44+
"reference_start_line": null,
45+
"reference_end_line": null
46+
}
47+
],
48+
"assigned_files": [],
49+
"can_expand": false
50+
},
51+
{
52+
"name": "Unclassified",
53+
"description": "Component for all unclassified files and utility functions (Utility functions/External Libraries/Dependencies)",
54+
"referenced_source_code": [],
55+
"assigned_files": [],
56+
"can_expand": false
57+
}
58+
],
59+
"components_relations": [
60+
{
61+
"relation": "provides access tokens to",
62+
"src_name": "OAuth Handler",
63+
"dst_name": "Bearer Token Manager"
64+
},
65+
{
66+
"relation": "applies tokens to",
67+
"src_name": "Bearer Token Manager",
68+
"dst_name": "External HTTP Requests"
69+
}
70+
]
71+
}

‎.codeboarding/Authentication_Service.mdx‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
# Authentication Service
2+
```mermaid
3+
graph LR
4+
OAuth_Handler["OAuth Handler"]
5+
Bearer_Token_Manager["Bearer Token Manager"]
6+
External_HTTP_Requests["External HTTP Requests"]
7+
Unclassified["Unclassified"]
8+
OAuth_Handler -- "provides access tokens to" --> Bearer_Token_Manager
9+
Bearer_Token_Manager -- "applies tokens to" --> External_HTTP_Requests
10+
```
11+
12+
### Details
13+
14+
The authentication subsystem in `mcp_use.auth` is designed to handle OAuth 2.0 authentication flows and apply bearer tokens to outgoing HTTP requests. The `OAuth Handler` component, implemented by the `mcp_use.auth.oauth.OAuth` class, is responsible for orchestrating the OAuth process, including discovering server capabilities, dynamic client registration, and managing token storage. Once access tokens are acquired, the `Bearer Token Manager` component, implemented by `mcp_use.auth.bearer.BearerAuth`, takes these tokens and applies them as `Authorization: Bearer` headers to `External HTTP Requests`. This ensures secure communication with external services, such as MCP servers. The `OAuth Handler` provides the necessary access tokens to the `Bearer Token Manager`, which then uses them to authenticate `External HTTP Requests`.
15+
16+
### OAuth Handler
17+
Manages the entire OAuth 2.0 protocol flow. This includes initiating authentication requests with external OAuth providers, handling redirects, and securely obtaining and storing access tokens. It acts as the primary interface for acquiring the necessary authentication credentials.
18+
19+
20+
**Related Classes/Methods**:
21+
22+
- <a href="https://github.com/mcp-use/mcp-use/blob/main/mcp_use/auth/oauth.py#L167-L625" target="_blank" rel="noopener noreferrer">QName:`mcp_use.auth.oauth.OAuth` FileRef: `mcp_use/auth/oauth.py`, Lines:(167:625)</a>
23+
24+
25+
### Bearer Token Manager
26+
Responsible for taking an acquired access token (typically from the OAuth Handler) and correctly formatting it as a bearer token. It then integrates this token into the Authorization header of outgoing HTTP requests, ensuring secure and authenticated communication with MCP servers.
27+
28+
29+
**Related Classes/Methods**:
30+
31+
- <a href="https://github.com/mcp-use/mcp-use/blob/main/mcp_use/auth/bearer.py#L9-L17" target="_blank" rel="noopener noreferrer">QName:`mcp_use.auth.bearer.BearerAuth` FileRef: `mcp_use/auth/bearer.py`, Lines:(9:17)</a>
32+
33+
34+
### External HTTP Requests
35+
Represents any HTTP requests made to external services or APIs, typically to MCP servers, that require authentication.
36+
37+
38+
**Related Classes/Methods**:
39+
40+
- QName:`requests.request` FileRef: ``
41+
42+
43+
### Unclassified
44+
Component for all unclassified files and utility functions (Utility functions/External Libraries/Dependencies)
45+
46+
47+
**Related Classes/Methods**: _None_

0 commit comments

Comments
 (0)