10up/localwp-agent-tools

AI 기반 WordPress 개발을 위한 MCP 서버와 프로젝트 컨텍스트를 제공하는 로컬 애드온입니다. Claude Code, Cursor, Windsurf, VS Code Copilot 및 모든 MCP 클라이언트와 함께 작동합니다.

Local에서 사이트의 "Enable"을 클릭하면 이 애드온은 다음 작업을 수행합니다:

MCP 서버에 사이트를 등록합니다 — Local의 메인 프로세스 내에서 실행되는 단일 HTTP 서버로, AI 도구에 WP-CLI, 오류 로그, 구성 및 사이트 관리에 대한 액세스를 제공합니다.MCP 설정을 작성합니다 (.mcp.json, .cursor/mcp.json 등) — 올바른 HTTP 엔드포인트와 각 에이전트에 대한 설치별 bearer 토큰으로 자동 구성됩니다 (인증(Authentication) 참조).프로젝트 컨텍스트를 생성합니다 (CLAUDE.md, .cursorrules 등) — PHP/MySQL 버전, 활성 플러그인, 테마 및 파일 구조를 포함한 사이트 컨텍스트업데이트합니다 — 이제 MCP 설정 파일에는 생성된 컨텍스트 파일과 함께 비밀(bearer 토큰)이 포함되므로, 이들 모두는 git-ignored되며 커밋되지 않습니다 (.gitignore).

그런 다음 선택한 AI 도구에서 사이트 폴더를 열면 바로 사용할 준비가 됩니다.

MCP 서버는 Local의 Electron 메인 프로세스 내에서 단일 HTTP 서버로 실행됩니다 — 사이트별 별도의 Node.js 프로세스는 없습니다. 이 서버는 두 가지 종류의 엔드포인트를 제공합니다:

http://localhost:{port}/sites/mcp # 글로벌 — 모든 Local
http://localhost:{port}/sites/{siteId}/mcp # 특정 사이트 하나

이 서버는 MCP Streamable HTTP 전송을 사용합니다. 포트는 재시작 시에도 안정적입니다 ( ~/.local-agent-tools/port에 저장되며, 기본값은 24842입니다).

사이트는 중지되어도 등록 상태를 유지하므로 MCP 엔드포인트는 항상 접근 가능합니다. 실행 서비스가 필요한 도구(WP-CLI, 데이터베이스)는 적절한 오류를 반환하고; 파일 기반 도구(구성, 로그, 사이트 정보)는 관계없이 작동합니다. 구성은 각 도구 호출 시 새로 고쳐지므로, 사이트를 시작하는 것만으로도 데이터베이스 도구를 다시 연결할 필요 없이 사용할 수 있습니다.

MCP 서버로의 모든 요청에는 Authorization: Bearer <token> 헤더가 필요합니다. 이 헤더가 유일한 채널이며, ?token= URL 매개변수는 없습니다.

애드온은 첫 시작 시 토큰을 생성하고 이를 ~/.local-agent-tools/token에 모드 0600으로, 그리고 0700 디렉터리에 저장합니다. 이 토큰은 재시작에도 살아남으며, 서버는 이를 상수 시간(constant time)에 확인합니다.

이 토큰은 생성된 모든 MCP 설정 파일의 headers 필드 안에 존재합니다: .mcp.json, .cursor/mcp.json, .windsurf/mcp.json, 그리고 .vscode/mcp.json입니다. 이 파일들은 모두 모드 0600으로 작성되며, 각 파일과 그 .backup 사본은 프로젝트의 .gitignore에 추가됩니다. 애드온은 설정 파일을 다시 쓸 때마다(시작 시 포함) 이 .gitignore 블록을 새로 고칩니다.

Local을 한 번 재시작하세요. 시작 시 애드온은 활성화된 모든 사이트의 MCP 설정 파일을 현재 토큰으로 다시 작성하므로 수동 단계가 필요하지 않습니다.

그런 다음 MCP 클라이언트를 재시작하여 새 설정을 가져오게 하세요. 만약 클라이언트가 여전히 401 응답을 받는다면, Local의 Agent Tools 패널에서 해당 사이트를 열고 Regenerate Config를 클릭하세요.

현재 토큰을 교체하려면:

• Local을 종료합니다.
• ~/.local-agent-tools/token을 삭제합니다.
• Local을 시작합니다.

애드온은 시작 시 새 토큰을 생성하고 이를 모든 활성화된 사이트의 MCP 설정 파일에 다시 작성합니다.

Local과 동일한 사용자로 실행되는 프로세스는 토큰 파일과 이 토큰을 담고 있는 모든 MCP 설정 파일을 읽을 수 있습니다. 이 토큰은 다른 사용자, 다른 기기, 그리고 웹 페이지가 MCP 서버에 접근하는 것을 막습니다. 하지만 본인 계정으로 실행되는 다른 프로세스를 막지는 못합니다.

MCP 서버는 신뢰할 수 있는 로컬(trusted-local)로 간주하세요: 네트워크와 해당 기기의 다른 계정으로부터는 안전하지만, 사용자로서 실행되는 다른 소프트웨어로부터는 안전하지 않습니다.

Local은 애드온이 프로젝트 파일을 어디에 작성할지 선택할 수 있게 합니다: 사이트 루트(Site Root), 워드프레스 루트(WordPress Root) (app/public), 또는 wp-content입니다. 워드프레스 루트나 wp-content를 선택하면 MCP 설정 파일과 그 안에 있는 토큰이 해당 사이트의 웹 루트에 위치하여 Local의 웹 서버가 이를 제공할 수 있습니다. 다른 위치가 필요하지 않다면 사이트 루트를 선호하세요.

서버는 Host 헤더가 정확히 localhost:{port}인 요청에만 응답합니다.

또는 127.0.0.1:{port}

. 수동으로 작성한 MCP 설정 파일은 이 두 값 중 하나를 사용해야 합니다.

/sites/mcp

은 특정 사이트에 묶여 있지 않습니다. 한 번 구성하면 어떤 디렉토리에서든 사용할 수 있으므로, 먼저 사이트 폴더를 열 필요가 없습니다.

이 엔드포인트는 바인딩된 사이트가 필요 없는 도구들을 제공합니다:

• Local 자체를 다루는 도구들:
  list_sites,
  create_site,
  그리고 list_service_versions.
• 사이트 수명 주기 도구들,
  site_start 등, 명시적인 siteId가 필요한 도구들.
• 미리 보기 도구들.
  preview_list와 preview_destroy는 Local 자체를 다룹니다. preview_start는 이 엔드포인트에 사이트가 바인딩되어 있지 않기 때문에 siteId가 필요합니다.
• 사이트별로 Agent Tools의 활성화/비활성화를 처리하는 도구들:
  enable_agent_tools,
  disable_agent_tools,
  그리고 agent_tools_status.

이것은 글로벌 엔드포인트를 부트스트랩 방식으로 만드는 방법입니다. 여기에 연결하여 사이트를 생성하거나 찾고, 그 사이트에 Agent Tools를 활성화합니다. enable_agent_tools는 해당 사이트 범위 작업에 대한 자체 엔드포인트 URL을 반환합니다.

사이트별 도구들은 여기에서 제공되지 않습니다: wp_cli, 로그 리더, wp-config 도구들, get_site_info, 그리고 site_health_check. 이들은 바인딩된 사이트가 필요합니다. 글로벌 엔드포인트에서 이를 호출하면 해당 사이트별 엔드포인트를 가리키는 오류가 반환됩니다.

글로벌 엔드포인트는 개별 사이트 엔드포인트와 동일한 bearer token과 Host 및 Origin 검사를 사용합니다. 지속된 포트와 토큰을 사용하여 Claude Code에 추가하려면 다음 명령어를 사용하십시오:

claude mcp add --scope user --transport http local-wp-global \
"http://localhost:$(cat ~/.local-agent-tools/port)/sites/mcp" \
--header "Authorization: Bearer $(cat ~/.local-agent-tools/token)"

--scope user는 이것을 글로벌하게 만드는 부분입니다. 이것이 없으면, claude mcp add는 --scope local을 사용하며, 이는 명령어를 실행한 디렉토리에만 서버를 등록합니다. 이 서버에는 --scope project를 사용하지 마십시오: 프로젝트 범위의 .mcp.json은 리포지토리에 커밋되며, 이 항목이 토큰을 포함합니다.

또한 ~/.claude.json 파일의 최상위 레벨에 있는 mcpServers 항목으로 수동 추가할 수도 있습니다.

. Cursor, Windsurf, 그리고 VS Code는 애드온이 작성하는 사이트별 설정과 동일한 형태를 사용합니다.

{
"mcpServers": {
"local-wp-global": {
...

claude mcp list 명령은 연결을 확인해 줍니다.

글로벌 엔드포인트는 사이트 관리와 create_site 기능을 하나의 잘 알려진 URL 뒤에 배치합니다. 이전에는 이 기능들이 활성화된 사이트의 엔드포인트에서만 접근 가능했습니다. 토큰이 여전히 모든 요청을 통제하므로, What the token does not protect against에 명시된 신뢰 모델은 변함없이 적용됩니다.

새로운 WordPress 사이트를 Local에서 생성하고, 선택적으로 Agent Tools를 활성화할 수 있습니다 | |
list_service_versions |
create_site에 사용 가능한 PHP, 데이터베이스 및 웹 서버 버전 |
|
미리보기 (Preview) |
preview_start |
사이트를 자체 데이터베이스, 프로세스, 도메인 및 MCP 엔드포인트가 있는 일회용 미리보기 사이트로 복제합니다 |
preview_list |
미리보기 사이트와 해당 MCP 엔드포인트 URL 목록을 나열합니다 | |
preview_destroy |
미리보기 사이트를 삭제하며, 일반 사이트는 삭제하지 않습니다 | |
Agent Tools |
enable_agent_tools |
사이트에 Agent Tools를 활성화합니다: 등록하고 MCP 구성 및 컨텍스트 파일을 작성합니다 | |
disable_agent_tools |
사이트에서 Agent Tools를 비활성화하고 관련 내용을 제거합니다 | |
agent_tools_status |
Agent Tools가 활성화된 사이트, 해당 에이전트 및 해당 MCP 엔드포인트 URL을 보고합니다 |

create_site

Local의 자체 사이트 추가(Add Site) 흐름과 동일한 코드 경로를 따르므로, 새 사이트는 프로비저닝된 서비스와 실제 WordPress 설치를 얻게 됩니다:

create_site({ name: "Client Redesign", phpVersion: "8.2.29", enableAgentTools: true })

알아두어야 할 세 가지 사항이 있습니다:

사이트가 준비되기 전에 반환됩니다. 프로비저닝에는 1분 이상 걸릴 수 있으며, Local이 서비스 바이너리를 먼저 다운로드해야 하는 경우 더 오래 걸리므로 대부분의 MCP 클라이언트 요청 시간 초과(request timeout)를 훨씬 넘어섭니다. 호출은 사이트가 등록되는 즉시 반환되며, site_status는 adding → provisioning → running을 보고합니다. 이 상태가 running을 보고할 때까지 폴링(poll)하세요. 클라이언트가 긴 도구 호출을 허용하는 경우에만 블록하기 위해 wait: true를 전달하십시오.Local은 사용자 비밀번호를 요청할 수 있습니다. Local이 localhost 라우터 모드로 설정되지 않은 한, 프로비저닝 과정에서 /etc/hosts를 업데이트합니다. macOS/Windows에서는 관리자 자격 증명을 요청할 것입니다. 사이트 생성은 결코 완전히 무인(unattended)으로 이루어지지 않습니다.실패는 다음 폴링에서 나타납니다. 호출이 반환된 후 프로비저닝에 실패하면, site_status에는 이유를 설명하는 creationError 필드가 포함됩니다.

phpVersion, database 및 webServer를 생략하면 Local의 기본값을 사용하며, list_service_versions를 호출할 수 있습니다.

사용 가능한 기능을 확인하는 첫 번째 방법입니다. installed: false로 보고된 버전은 필요할 때 다운로드되므로 생성 시간이 상당히 느립니다.

enableAgentTools: true를 사용하면, Agent Tools가 사이트 프로비저닝을 완료한 후 활성화됩니다. 이는 UI에서 활성화(Enable) 버튼을 클릭하는 것과 정확히 동일하게 MCP 서버에 등록하고 MCP 설정 및 컨텍스트 파일을 작성합니다. 어떤 도구를 사용할지 선택하려면 agents를 사용하세요 (기본값은 ["claude"]입니다).

git clone <repo-url> agent-tools
cd agent-tools
npm install --legacy-peer-deps
...

빌드된 애드온을 Local의 애드온 디렉터리에 복사합니다:

# macOS
cp -r . ~/Library/Application\ Support/Local/addons/agent-tools/
# Linux
...

설치 위치에 프로덕션 종속성을 설치하고 Local을 다시 시작합니다:

# macOS
cd ~/Library/Application\ Support/Local/addons/agent-tools/
# Linux
...

npm install --production --ignore-scripts
# 그런 다음 Local을 재시작하세요

# 애드온 빌드하기
npm run build
# 변경 사항 감지
...

빌드 후, 설치된 애드온과 동기화합니다:

# macOS
cp -R lib/* ~/Library/Application\ Support/Local/addons/agent-tools/lib/
# Linux
...

그런 다음 Local을 다시 시작하여 변경 사항을 반영합니다.

agent-tools/
├── src/ # 애드온 소스 (TypeScript)
│ ├── main.ts # 메인 프로세스 — 라이프사이클 후크, IPC, MCP 서버 시작
...

• Local 9.0 이상
• MCP와 호환되는 AI 도구 (Claude Code, Cursor, Windsurf, VS Code Copilot 등)

macOS (darwin-arm64 및 darwin-x64), Windows, 그리고 Linux.

활성 상태: 10up은 이 부분에 대해 적극적으로 작업하고 있으며, 테스트를 거쳐 가장 최신 버전의 Local까지 유지하는 것을 포함하여 가까운 미래에도 작업을 계속할 것으로 예상합니다. 버그 보고서, 기능 요청, 질문 및 풀 리퀘스트는 환영합니다.

Agent Tools의 모든 주목할 만한 변경 사항 목록은 CHANGELOG.md에 문서화되어 있습니다.

코드 윤리 강령(CODE_OF_CONDUCT.md)을 읽어보시고, 기여하는 방법(CONTRIBUTING.md)에 대한 자세한 내용을 확인하시고, Agent Tools의 유지 관리자, 기여자 및 라이브러리 목록은 CREDITS.md를 참고해 주세요.