mirror of
https://gitea.com/mcereda/oam.git
synced 2026-02-22 19:44:25 +00:00
chore(kb/ai): review and expand notes
This commit is contained in:
Michele Cereda
@@ -18,6 +18,7 @@ TODO
|
||||
## Further readings
|
||||
|
||||
- [Large Language Model] (LLM)
|
||||
- [Model Context Protocol] (MCP)
|
||||
- [Useful AI]: tools, courses, and more, curated and reviewed by experts.
|
||||
|
||||
### Sources
|
||||
@@ -29,7 +30,8 @@ TODO
|
||||
|
||||
<!-- In-article sections -->
|
||||
<!-- Knowledge base -->
|
||||
[Large Language Model]: large%20language%20model.md
|
||||
[Large Language Model]: llm.md
|
||||
[Model Context Protocol]: mcp.md
|
||||
|
||||
<!-- Files -->
|
||||
<!-- Upstream -->
|
||||
|
||||
@@ -124,7 +124,7 @@ See [An AI Agent Published a Hit Piece on Me] by Scott Shambaugh.
|
||||
<!-- Knowledge base -->
|
||||
[Claude Code]: claude/claude%20code.md
|
||||
[Gemini CLI]: gemini/cli.md
|
||||
[Large Language Model]: large%20language%20model.md
|
||||
[Large Language Model]: llm.md
|
||||
[OpenCode]: opencode.md
|
||||
|
||||
<!-- Others -->
|
||||
|
||||
@@ -62,7 +62,7 @@ AI platform built by Anthropic.
|
||||
<!-- In-article sections -->
|
||||
<!-- Knowledge base -->
|
||||
[Gemini]: ../gemini/README.md
|
||||
[Large Language Model]: ../large%20language%20model.md
|
||||
[Large Language Model]: ../llm.md
|
||||
|
||||
<!-- Files -->
|
||||
<!-- Upstream -->
|
||||
|
||||
@@ -9,6 +9,8 @@ Works in a terminal, IDE, browser, and as a desktop app.
|
||||
## Table of contents <!-- omit in toc -->
|
||||
|
||||
1. [TL;DR](#tldr)
|
||||
1. [Grant access to tools](#grant-access-to-tools)
|
||||
1. [Using skills](#using-skills)
|
||||
1. [Run on local models](#run-on-local-models)
|
||||
1. [Further readings](#further-readings)
|
||||
1. [Sources](#sources)
|
||||
@@ -25,7 +27,7 @@ When multiple scopes are active, the **more** specific ones take precedence.
|
||||
| Scope | Location | Area of effect | Shared |
|
||||
| ----------------------- | ------------------------------------ | ---------------------------------- | ----------------------------------------- |
|
||||
| Managed (A.K.A. System) | System-level `managed-settings.json` | All users on the host | Yes (usually deployed by IT) |
|
||||
| User | `~/.claude/` directory | Single user, across all projects | No |
|
||||
| User | `$HOME/.claude/` directory | Single user, across all projects | No |
|
||||
| Project | `.claude/` directory in a repository | All collaborators, repository only | Yes (usually committed to the repository) |
|
||||
| Local | `.claude/*.local.*` files | Single user, repository only | No (usually gitignored) |
|
||||
|
||||
@@ -58,8 +60,24 @@ claude -c
|
||||
# Resume a previous conversation
|
||||
claude -r
|
||||
|
||||
# Add MCPs
|
||||
claude mcp add --transport 'sse' 'linear-server' 'https://mcp.linear.app/sse'
|
||||
# Add MCP servers.
|
||||
# Defaults to the 'local' scope if not specified.
|
||||
claude mcp add --transport 'http' 'linear' 'https://mcp.linear.app/mcp' --scope 'user'
|
||||
|
||||
# List configured MCP servers.
|
||||
claude mcp list
|
||||
|
||||
# Show MCP servers' details
|
||||
claude mcp get 'github'
|
||||
|
||||
# Remove MCP servers.
|
||||
claude mcp remove 'github'
|
||||
```
|
||||
|
||||
From within Claude Code:
|
||||
|
||||
```plaintext
|
||||
/mcp
|
||||
```
|
||||
|
||||
</details>
|
||||
@@ -75,6 +93,126 @@ ANTHROPIC_AUTH_TOKEN='ollama' ANTHROPIC_BASE_URL='http://localhost:11434' ANTHRO
|
||||
|
||||
</details>
|
||||
|
||||
## Grant access to tools
|
||||
|
||||
Add MCP servers to give Claude Code access to tools, databases, and APIs in general.
|
||||
|
||||
> [!caution]
|
||||
> MCPs are **not** verified, nor otherwise checked for security issues.<br/>
|
||||
> Be especially careful when using MCP servers that cat fetch untrusted content, as they can fall victim of prompt
|
||||
> injections.
|
||||
|
||||
Procedure:
|
||||
|
||||
1. Add the desired MCP server.
|
||||
|
||||
<details style='padding: 0 0 1rem 1rem'>
|
||||
<summary>Examples</summary>
|
||||
|
||||
```sh
|
||||
claude mcp add --transport 'http' 'linear' 'https://mcp.linear.app/mcp' --scope 'user'
|
||||
```
|
||||
|
||||
1. From within Claude Code, run the `/mcp` command to configure it.
|
||||
|
||||
<details>
|
||||
<summary>AWS API MCP server</summary>
|
||||
|
||||
Refer [AWS API MCP Server].
|
||||
|
||||
Enables AI assistants to interact with AWS services and resources through AWS CLI commands.
|
||||
|
||||
<details style='padding: 0 0 1rem 1rem'>
|
||||
<summary>Run as Docker container</summary>
|
||||
|
||||
Manually add the MCP server definition to `$HOME/.claude.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"aws-api": {
|
||||
"command": "docker",
|
||||
"args": [
|
||||
"run",
|
||||
"--rm",
|
||||
"--interactive",
|
||||
"--env",
|
||||
"AWS_REGION=eu-west-1",
|
||||
"--env",
|
||||
"AWS_API_MCP_TELEMETRY=false",
|
||||
"--env",
|
||||
"REQUIRE_MUTATION_CONSENT=true",
|
||||
"--env",
|
||||
"READ_OPERATIONS_ONLY=true",
|
||||
"--volume",
|
||||
"/Users/yourUserHere/.aws:/app/.aws",
|
||||
"public.ecr.aws/awslabs-mcp/awslabs/aws-api-mcp-server:latest"
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary>AWS Cost Explorer MCP server</summary>
|
||||
|
||||
Refer [Cost Explorer MCP Server].
|
||||
|
||||
Enables AI assistants to analyze AWS costs and usage data through the AWS Cost Explorer API.
|
||||
|
||||
<details style='padding: 0 0 1rem 1rem'>
|
||||
<summary>Run as Docker container</summary>
|
||||
|
||||
FIXME: many of those environment variable are probably unnecessary here.
|
||||
|
||||
Manually add the MCP server definition to `$HOME/.claude.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"aws-cost-explorer": {
|
||||
"command": "docker",
|
||||
"args": [
|
||||
"run",
|
||||
"--rm",
|
||||
"--interactive",
|
||||
"--env",
|
||||
"AWS_REGION=eu-west-1",
|
||||
"--env",
|
||||
"AWS_API_MCP_TELEMETRY=false",
|
||||
"--env",
|
||||
"REQUIRE_MUTATION_CONSENT=true",
|
||||
"--env",
|
||||
"READ_OPERATIONS_ONLY=true",
|
||||
"--volume",
|
||||
"/Users/yourUserHere/.aws:/app/.aws",
|
||||
"public.ecr.aws/awslabs-mcp/awslabs/cost-explorer-mcp-server:latest"
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
</details>
|
||||
|
||||
## Using skills
|
||||
|
||||
Claude Code automatically discovers skills from:
|
||||
|
||||
- The user's `$HOME/.claude/skills/` directory, and sets them up as user-level skills.
|
||||
- The project's `.claude/skills/` folder, and sets them up as project-level skills.
|
||||
|
||||
User-level skills are available in all projects.<br/>
|
||||
Project-level skills are limited to the current project.
|
||||
|
||||
Claude Code activates relevant skills automatically based on the request context.
|
||||
|
||||
## Run on local models
|
||||
|
||||
Claude _can_ use other models and engines by setting the `ANTHROPIC_AUTH_TOKEN`, `ANTHROPIC_BASE_URL` and
|
||||
@@ -154,4 +292,6 @@ Claude Code version: `v2.1.41`.<br/>
|
||||
[Website]: https://claude.com/product/overview
|
||||
|
||||
<!-- Others -->
|
||||
[AWS API MCP Server]: https://github.com/awslabs/mcp/tree/main/src/aws-api-mcp-server
|
||||
[Cost Explorer MCP Server]: https://github.com/awslabs/mcp/tree/main/src/cost-explorer-mcp-server
|
||||
[pffigueiredo/claude-code-sheet.md]: https://gist.github.com/pffigueiredo/252bac8c731f7e8a2fc268c8a965a963
|
||||
|
||||
@@ -64,7 +64,7 @@ Intro
|
||||
<!-- Knowledge base -->
|
||||
[Claude]: ../claude/README.md
|
||||
[CLI]: cli.md
|
||||
[Large Language Model]: ../large%20language%20model.md
|
||||
[Large Language Model]: ../llm.md
|
||||
|
||||
<!-- Files -->
|
||||
<!-- Upstream -->
|
||||
|
||||
84
knowledge base/ai/mcp.md
Normal file
84
knowledge base/ai/mcp.md
Normal file
@@ -0,0 +1,84 @@
|
||||
# Model Context Protocol
|
||||
|
||||
Open protocol enabling seamless integration between AI applications and external data sources and tools by providing
|
||||
a standardized way to enable LLMs to access key information and perform tasks.
|
||||
|
||||
1. [TL;DR](#tldr)
|
||||
1. [Further readings](#further-readings)
|
||||
1. [Sources](#sources)
|
||||
|
||||
## TL;DR
|
||||
|
||||
MCP consists of:
|
||||
|
||||
- The _data_ layer, defining the JSON-RPC based protocol for client-server communication.<br/>
|
||||
It includes lifecycle management and core primitives, e.g. tools, resources, prompts and notifications.
|
||||
- The _transport_ layer, defining the communication mechanisms and channels that enable data exchange between clients
|
||||
and servers.<br/>
|
||||
It includes transport-specific connection establishment, message framing, and authorization.
|
||||
|
||||
MCP _hosts_ are AI applications users can interact with, and that coordinate and manage one or more MCP clients.<br/>
|
||||
MCP _clients_ are components that connect to a single MCP server to gather context from it for the host to use.<br/>
|
||||
MCP _servers_ are applications providing context data to one or more MCP clients.
|
||||
|
||||
MCP hosts create one MCP client for each MCP server they use.<br/>
|
||||
Each client maintains a dedicated connection with its corresponding server.
|
||||
|
||||
Servers provide functionality through _tools_, _resources_, and _prompts_.<br/>
|
||||
_Tools_ are functions that an LLM can **actively** call to take actions, i.e. writing to databases, calling external
|
||||
APIs, modifying files, or triggering other logic. The LLM decides when to use them based on user requests.<br/>
|
||||
_Resources_ are **passive** data sources providing **read-only** access to information for context, such as files,
|
||||
database schemas, or API documentation.<br/>
|
||||
_Prompts_ are pre-built instruction templates telling the model reading them how to work with specific tools and
|
||||
resources.
|
||||
|
||||
Clients _can_ provide features to servers, aside from making use of the context they provide.<br/>
|
||||
Client features allow server authors to build richer interactions through _elicitation_, _roots_, and _sampling_.
|
||||
_Elicitation_ enables servers to request specific information from users.<br/>
|
||||
_Roots_ define filesystem boundaries for server operations, allowing clients to specify which folders servers should
|
||||
focus on.<br/>
|
||||
_Sampling_ allows servers to request LLM completions through the client. This is what enables an agentic workflow.
|
||||
|
||||
MCP uses string-based version identifiers that follow the `YYYY-MM-DD` format.<br/>
|
||||
Versions indicate the **last** date that backwards incompatible changes were made in the protocol.
|
||||
|
||||
Version negotiation happens during initialization.<br/>
|
||||
Clients and servers _may_ support multiple protocol versions simultaneously, but they _**must**_ agree on a single
|
||||
version to use for the session.<br/>
|
||||
The protocol provides error handling if version negotiation fails, which allows clients to gracefully terminate
|
||||
connections when they cannot find a version compatible with the server.
|
||||
|
||||
MCP servers of interest:
|
||||
|
||||
| MCP server | Summary |
|
||||
| ------------------------------------------------- | ------------------------------------------------------ |
|
||||
| [AWS API][aws api mcp server] | Interact with all available AWS services and resources |
|
||||
| [AWS Cost Explorer][aws cost explorer mcp server] | Analyze AWS costs and usage data |
|
||||
|
||||
## Further readings
|
||||
|
||||
- [Website]
|
||||
- [Codebase]
|
||||
- [Blog]
|
||||
|
||||
### Sources
|
||||
|
||||
- [Documentation]
|
||||
|
||||
<!--
|
||||
Reference
|
||||
═╬═Time══
|
||||
-->
|
||||
|
||||
<!-- In-article sections -->
|
||||
<!-- Knowledge base -->
|
||||
<!-- Files -->
|
||||
<!-- Upstream -->
|
||||
[Blog]: https://blog.modelcontextprotocol.io/
|
||||
[Codebase]: https://github.com/modelcontextprotocol
|
||||
[Documentation]: https://modelcontextprotocol.io/docs/
|
||||
[Website]: https://modelcontextprotocol.io
|
||||
|
||||
<!-- Others -->
|
||||
[AWS API MCP Server]: https://github.com/awslabs/mcp/tree/main/src/aws-api-mcp-server
|
||||
[AWS Cost Explorer MCP Server]: https://github.com/awslabs/mcp/tree/main/src/cost-explorer-mcp-server
|
||||
@@ -127,7 +127,7 @@
|
||||
<!-- Knowledge base -->
|
||||
[Docker]: ../docker.md
|
||||
[Docker Running LLMs locally]: ../docker.md#running-llms-locally
|
||||
[Large Language Model]: large%20language%20model.md
|
||||
[Large Language Model]: llm.md
|
||||
[Ollama]: ollama.md
|
||||
|
||||
<!-- Files -->
|
||||
|
||||
@@ -5,10 +5,10 @@
|
||||
| Acronym | Expansion | Summary |
|
||||
| ------- | ------------------------------------------------------ | --------------------------------------------------------------------------------------------------- |
|
||||
| ACK | ACKnowledgement | |
|
||||
| ACL | [Access Control List][acl] | |
|
||||
| ACL | [Access Control List] | |
|
||||
| ACME | [Automatic Certificate Management Environment] | Protocol to automate the issuance and renewal of certificates without human interaction |
|
||||
| AD | Active Directory | |
|
||||
| ADR | [Architectural Decision Record][adr] | |
|
||||
| ADR | [Architectural Decision Record] | |
|
||||
| API | Application Programming Interface | A way for two or more computer programs or components to communicate with each other |
|
||||
| APK | Alpine Package Keeper | Package manager used by Alpine Linux |
|
||||
| APT | Advanced Package Tool | Package manager used by Debian Linux |
|
||||
@@ -32,7 +32,7 @@
|
||||
| CMS | Content Management System | |
|
||||
| CN | Canonical Name | In Active Directory, the full path of an object in a canonical format |
|
||||
| CN | Common Name | In Active Directory, the last element in an object's Distinguished Name (DN) hierarchy |
|
||||
| CNI | [Container Network Interface][cni] | |
|
||||
| CNI | [Container Network Interface] | |
|
||||
| COTS | Commercial Off-The-Shelf | Available _as-is_, not optimized for specific scopes or objectives |
|
||||
| CSMA | Carrier-Sense Multiple Access | |
|
||||
| CSMA/CD | Carrier-Sense Multiple Access with Collision Detection | |
|
||||
@@ -92,6 +92,7 @@
|
||||
| LIFO | Last In First Out | |
|
||||
| LLM | [Large Language Model] | |
|
||||
| M2COTS | Mass Market COTS | Widely available COTS products |
|
||||
| MCP | [Model Context Protocol] | |
|
||||
| MR | Merge Request | Prevalently used in GitLab |
|
||||
| NACL | Network ACL | |
|
||||
| NIST | National Institute of Science and Technology | |
|
||||
@@ -172,18 +173,19 @@
|
||||
-->
|
||||
|
||||
<!-- Knowledge base -->
|
||||
[acl]: acl.md
|
||||
[adr]: adr.md
|
||||
[Access Control List]: acl.md
|
||||
[Architectural Decision Record]: adr.md
|
||||
[bash]: bash.md
|
||||
[cni]: cni.md
|
||||
[Container Network Interface]: cni.md
|
||||
[data warehouse]: data%20warehouse.md
|
||||
[depin]: depin.md
|
||||
[fhs]: filesystem%20hierarchy%20standard.md
|
||||
[fish]: fish.md
|
||||
[iac]: iac.md
|
||||
[kubernetes]: kubernetes/README.md
|
||||
[Large Language Model]: ai/large%20language%20model.md
|
||||
[Large Language Model]: ai/llm.md
|
||||
[lora]: lora.md
|
||||
[Model Context Protocol]: ai/mcp.md
|
||||
[siem]: siem.md
|
||||
[snowflake]: snowflake/README.md
|
||||
[ssh]: ssh.md
|
||||
|
||||
Reference in New Issue
Block a user