{"owner":"microsoft","repo":"mcp-for-beginners","hasSkills":true,"hasMcp":true,"mcpConfig":{"mcpServers":{"mcp-for-beginners":{"command":"npx","args":["-y","@modelcontextprotocol/server-mcp-for-beginners"]}}},"found":["AGENTS.md"],"skills":{"AGENTS.md":"# AGENTS.md\n\n## Project Overview\n\n**MCP for Beginners** is an open-source educational curriculum for learning the Model Context Protocol (MCP) - a standardized framework for interactions between AI models and client applications. This repository provides comprehensive learning materials with hands-on code examples across multiple programming languages.\n\n### Key Technologies\n\n- **Programming Languages**: C#, Java, JavaScript, TypeScript, Python, Rust\n- **Frameworks & SDKs**: \n - MCP SDK (`@modelcontextprotocol/sdk`)\n - Spring Boot (Java)\n - FastMCP (Python)\n - LangChain4j (Java)\n- **Databases**: PostgreSQL with pgvector extension\n- **Cloud Platforms**: Azure (Container Apps, OpenAI, Content Safety, Application Insights)\n- **Build Tools**: npm, Maven, pip, Cargo\n- **Documentation**: Markdown with automated multi-language translation (48+ languages)\n\n### Architecture\n\n- **11 Core Modules (00-11)**: Sequential learning path from fundamentals to advanced topics\n- **Hands-on Labs**: Practical exercises with complete solution code in multiple languages\n- **Sample Projects**: Working MCP server and client implementations\n- **Translation System**: Automated GitHub Actions workflow for multi-language support\n- **Image Assets**: Centralized images directory with translated versions\n\n## Setup Commands\n\nThis is a documentation-focused repository. Most setup occurs within individual sample projects and labs.\n\n### Repository Setup\n\n```bash\n# Clone the repository\ngit clone https://github.com/microsoft/mcp-for-beginners.git\ncd mcp-for-beginners\n```\n\n### Working with Sample Projects\n\nSample projects are located in:\n- `03-GettingStarted/samples/` - Language-specific examples\n- `03-GettingStarted/01-first-server/solution/` - First server implementations\n- `03-GettingStarted/02-client/solution/` - Client implementations\n- `11-MCPServerHandsOnLabs/` - Comprehensive database integration labs\n\nEach sample project contains its own setup instructions:\n\n#### TypeScript/JavaScript Projects\n```bash\ncd \nnpm install\nnpm start\n```\n\n#### Python Projects\n```bash\ncd \npip install -r requirements.txt\n# or\npip install -e .\npython main.py\n```\n\n#### Java Projects\n```bash\ncd \nmvn clean install\nmvn spring-boot:run\n```\n\n## Development Workflow\n\n### MCP 7-28 Readiness\n\n#### Repo readiness checklist\n\n- [x] **New contributor clarity**: This file defines repository purpose,\n structure, contribution rules, and sample setup paths.\n- [x] **Build/test/lint commands with exact flags**:\n - Repository docs lint:\n `npx --yes markdownlint-cli2 \"**/*.md\" \"#node_modules\" \"#translations\" \"#translated_images\"`\n - Repository docs link pattern audit:\n `find . -name \"*.md\" -not -path \"*/node_modules/*\" -not -path \"./translations/*\" -not -path \"./translated_images/*\" -print0 | xargs -0 grep -En \"\\[.*\\]\\(.*\\)\"`\n - TypeScript sample validation:\n `cd 03-GettingStarted/samples/typescript && npm ci && npm test && npm run build`\n - Python sample validation:\n `cd 10-StreamliningAIWorkflowsBuildingAnMCPServerWithAIToolkit/lab3/code/weather_mcp && python -m pip install -e . && pytest -q`\n - Java sample validation:\n `cd 03-GettingStarted/samples/java/calculator && mvn -B -ntp test verify`\n- [x] **One realistic workflow that can become an MCP tool**:\n `validate_curriculum_change`\n- [x] **Inputs/outputs are explicit** (see specification below).\n- [x] **Permissions and failure modes are documented** (see specification below).\n- [x] **CI testability is explicit** (deterministic commands, explicit\n exit codes, and machine-readable outputs).\n\n#### Candidate MCP tool workflow: `validate_curriculum_change`\n\n##### Goal\n\nValidate curriculum documentation changes and representative sample code\nhealth before merge.\n\n##### Inputs\n\n- `changed_paths: string[]` (required) - relative paths changed in PR.\n- `run_docs_lint: boolean` (default `true`)\n- `run_links_audit: boolean` (default `true`)\n- `run_samples: { typescript?: boolean, python?: boolean, java?: boolean }`\n (default all `false`)\n\n##### Outputs\n\n- `status: \"ok\" | \"failed\"`\n- `checks: Array<{ name: string, command: string, exit_code: number,\n summary: string }>`\n- `artifacts: Array<{ type: \"log\" | \"report\", path: string }>`\n- `failed_checks: string[]`\n\n##### Permissions\n\n- Read workspace files and write tool-generated artifacts (e.g., lint\n reports, test logs) only; no writes to `translations/` or\n `translated_images/`.\n- Execute local shell commands.\n- Optional network access only for package restore (`npm ci`,\n `python -m pip install`, `mvn` dependency resolution).\n- No permission to push, merge, or modify `translations/` or\n `translated_images/`.\n\n##### Failure modes\n\n- `E_NO_INPUT_PATHS`: `changed_paths` empty.\n- `E_INVALID_PATH`: input path escapes repository root.\n- `E_LINT_FAILED`: markdown lint exits non-zero.\n- `E_LINK_AUDIT_FAILED`: link audit command exits non-zero.\n- `E_SAMPLE_TEST_FAILED`: sample test/build exits non-zero.\n- `E_TIMEOUT`: command exceeded configured timeout.\n\n##### Recommended CI contract\n\nTo automate validation, configure a CI job that:\n\n- Triggers on pull requests touching `*.md`, sample code, or this file.\n- Runs the exact commands listed above.\n- Persists logs as artifacts.\n- Fails the job on any non-zero exit code.\n\n#### If you ship an MCP server from this repo\n\n- [ ] Read the draft changelog for MCP 7-28:\n \n- [ ] Run your server against SDK betas:\n \n- [ ] Remove session and handshake assumptions; treat each request as\n self-contained:\n \n- [ ] Send `Mcp-Method` and `Mcp-Name` headers for raw HTTP requests:\n \n- [ ] Audit hardcoded error codes (`missing resource` moved from `-32002` to `-32602`).\n- [ ] Flag and plan migration for deprecated roots, sampling, and\n logging:\n \n- [ ] Migrate off the experimental `2025-11-25` Tasks API:\n \n- [ ] Review authorization for OAuth and OpenID Connect hardening:\n \n\n### Documentation Structure\n\n- **Modules 00-11**: Core curriculum content in sequential order\n- **translations/**: Language-specific versions (auto-generated, do not edit directly)\n- **translated_images/**: Localized image versions (auto-generated)\n- **images/**: Source images and diagrams\n\n### Making Documentation Changes\n\n1. Edit only the English markdown files in the root module directories (00-11)\n2. Update images in the `images/` directory if needed\n3. The co-op-translator GitHub Action will automatically generate translations\n4. Translations are regenerated on push to main branch\n\n### Working with Translations\n\n- **Automated Translation**: GitHub Actions workflow handles all translations\n- **Do NOT manually edit** files in `translations/` directory\n- Translation metadata is embedded in each translated file\n- Supported languages: 48+ languages including Arabic, Chinese, French, German, Hindi, Japanese, Korean, Portuguese, Russian, Spanish, and many more\n\n## Testing Instructions\n\n### Documentation Validation\n\nSince this is primarily a documentation repository, testing focuses on:\n\n1. **Link Pattern Audit**: List Markdown links for review\n\n ```bash\n # List Markdown links (pattern audit)\n find . -name \"*.md\" -not -path \"*/node_modules/*\" -not -path \"./translations/*\" -not -path \"./translated_images/*\" -print0 | xargs -0 grep -En \"\\[.*\\]\\(.*\\)\"\n ```\n\n2. **Code Sample Validation**: Test that code examples compile/run\n\n ```bash\n # Navigate to specific sample and run its tests\n cd 03-GettingStarted/samples/typescript\n npm install && npm test\n ```\n\n3. **Markdown Linting**: Check formatting consistency\n\n ```bash\n # Use markdownlint if needed\n npx --yes markdownlint-cli2 \"**/*.md\" \"#node_modules\" \"#translations\" \"#translated_images\"\n ```\n\n### Sample Project Testing\n\nEach language-specific sample includes its own testing approach:\n\n#### TypeScript/JavaScript\n```bash\nnpm test\nnpm run build\n```\n\n#### Python\n```bash\npytest\npython -m pytest tests/\n```\n\n#### Java\n```bash\nmvn test\nmvn verify\n```\n\n## Code Style Guidelines\n\n### Documentation Style\n\n- Use clear, beginner-friendly language\n- Include code examples in multiple languages where applicable\n- Follow markdown best practices:\n - Use ATX-style headers (`#` syntax)\n - Use fenced code blocks with language identifiers\n - Include descriptive alt text for images\n - Keep line lengths reasonable (no hard limit, but be sensible)\n\n### Code Sample Style\n\n#### TypeScript/JavaScript\n- Use ES modules (`import`/`export`)\n- Follow TypeScript strict mode conventions\n- Include type annotations\n- Target ES2022\n\n#### Python\n- Follow PEP 8 style guidelines\n- Use type hints where appropriate\n- Include docstrings for functions and classes\n- Use modern Python features (3.8+)\n\n#### Java\n- Follow Spring Boot conventions\n- Use Java 21 features\n- Follow standard Maven project structure\n- Include Javadoc comments\n\n### File Organization\n\n```\n-/\n├── README.md # Main module content\n├── samples/ # Code examples (if applicable)\n│ ├── typescript/\n│ ├── python/\n│ ├── java/\n│ └── ...\n└── solution/ # Complete working solutions\n └── /\n```\n\n## Build and Deployment\n\n### Documentation Deployment\n\nThe repository uses GitHub Pages or similar for documentation hosting (if applicable). Changes to the main branch trigger:\n\n1. Translation workflow (`.github/workflows/co-op-translator.yml`)\n2. Automated translation of all English markdown files\n3. Image localization as needed\n\n### No Build Process Required\n\nThis repository primarily contains markdown documentation. No compilation or build step is needed for the core curriculum content.\n\n### Sample Project Deployment\n\nIndividual sample projects may have deployment instructions:\n- See `03-GettingStarted/09-deployment/` for MCP server deployment guidance\n- Azure Container Apps deployment examples in `11-MCPServerHandsOnLabs/`\n\n## Contributing Guidelines\n\n### Pull Request Process\n\n1. **Fork and Clone**: Fork the repository and clone your fork locally\n2. **Create a Branch**: Use descriptive branch names (e.g., `fix/typo-module-3`, `add/python-example`)\n3. **Make Changes**: Edit English markdown files only (not translations)\n4. **Test Locally**: Verify markdown renders correctly\n5. **Submit PR**: Use clear PR titles and descriptions\n6. **CLA**: Sign the Microsoft Contributor License Agreement when prompted\n\n### PR Title Format\n\nUse clear, descriptive titles:\n- `[Module XX] Brief description` for module-specific changes\n- `[Samples] Description` for sample code changes\n- `[Docs] Description` for general documentation updates\n\n### What to Contribute\n\n- Bug fixes in documentation or code samples\n- New code examples in additional languages\n- Clarifications and improvements to existing content\n- New case studies or practical examples\n- Issue reports for unclear or incorrect content\n\n### What NOT to Do\n\n- Do not directly edit files in `translations/` directory\n- Do not edit `translated_images/` directory\n- Do not add large binary files without discussion\n- Do not change translation workflow files without coordination\n\n## Additional Notes\n\n### Repository Maintenance\n\n- **Changelog**: All significant changes are documented in `changelog.md`\n- **Study Guide**: Use `study_guide.md` for curriculum navigation overview\n- **Issue Templates**: Use GitHub issue templates for bug reports and feature requests\n- **Code of Conduct**: All contributors must follow the Microsoft Open Source Code of Conduct\n\n### Learning Path\n\nFollow modules in sequential order (00-11) for optimal learning:\n1. **00-02**: Fundamentals (Introduction, Core Concepts, Security)\n2. **03**: Getting Started with hands-on implementation\n3. **04-05**: Practical implementation and advanced topics\n4. **06-10**: Community, best practices, and real-world applications\n5. **11**: Comprehensive database integration labs (13 sequential labs)\n\n### Support Resources\n\n- **Documentation**: https://modelcontextprotocol.io/\n- **Specification**: https://spec.modelcontextprotocol.io/\n- **Community**: https://github.com/orgs/modelcontextprotocol/discussions\n- **Discord**: Microsoft Foundry Discord server\n- **Related Courses**: See README.md for other Microsoft learning paths\n\n### Common Troubleshooting\n\n**Q: My PR is failing the translation check**\nA: Ensure you only edited English markdown files in the root module directories, not translated versions.\n\n**Q: How do I add a new language?**\nA: Language support is managed through the co-op-translator workflow. Open an issue to discuss adding new languages.\n\n**Q: Code samples aren't working**\nA: Ensure you've followed the setup instructions in the specific sample's README. Check that you have the correct versions of dependencies installed.\n\n**Q: Images aren't displaying**\nA: Verify image paths are relative and use forward slashes. Images should be in the `images/` directory or `translated_images/` for localized versions.\n\n### Performance Considerations\n\n- Translation workflow may take several minutes to complete\n- Large images should be optimized before committing\n- Keep individual markdown files focused and reasonably sized\n- Use relative links for better portability\n\n### Project Governance\n\nThis project follows Microsoft open source practices:\n- MIT License for code and documentation\n- Microsoft Open Source Code of Conduct\n- CLA required for contributions\n- Security issues: Follow SECURITY.md guidelines\n- Support: See SUPPORT.md for help resources\n"},"files":{"AGENTS.md":"# AGENTS.md\n\n## Project Overview\n\n**MCP for Beginners** is an open-source educational curriculum for learning the Model Context Protocol (MCP) - a standardized framework for interactions between AI models and client applications. This repository provides comprehensive learning materials with hands-on code examples across multiple programming languages.\n\n### Key Technologies\n\n- **Programming Languages**: C#, Java, JavaScript, TypeScript, Python, Rust\n- **Frameworks & SDKs**: \n - MCP SDK (`@modelcontextprotocol/sdk`)\n - Spring Boot (Java)\n - FastMCP (Python)\n - LangChain4j (Java)\n- **Databases**: PostgreSQL with pgvector extension\n- **Cloud Platforms**: Azure (Container Apps, OpenAI, Content Safety, Application Insights)\n- **Build Tools**: npm, Maven, pip, Cargo\n- **Documentation**: Markdown with automated multi-language translation (48+ languages)\n\n### Architecture\n\n- **11 Core Modules (00-11)**: Sequential learning path from fundamentals to advanced topics\n- **Hands-on Labs**: Practical exercises with complete solution code in multiple languages\n- **Sample Projects**: Working MCP server and client implementations\n- **Translation System**: Automated GitHub Actions workflow for multi-language support\n- **Image Assets**: Centralized images directory with translated versions\n\n## Setup Commands\n\nThis is a documentation-focused repository. Most setup occurs within individual sample projects and labs.\n\n### Repository Setup\n\n```bash\n# Clone the repository\ngit clone https://github.com/microsoft/mcp-for-beginners.git\ncd mcp-for-beginners\n```\n\n### Working with Sample Projects\n\nSample projects are located in:\n- `03-GettingStarted/samples/` - Language-specific examples\n- `03-GettingStarted/01-first-server/solution/` - First server implementations\n- `03-GettingStarted/02-client/solution/` - Client implementations\n- `11-MCPServerHandsOnLabs/` - Comprehensive database integration labs\n\nEach sample project contains its own setup instructions:\n\n#### TypeScript/JavaScript Projects\n```bash\ncd \nnpm install\nnpm start\n```\n\n#### Python Projects\n```bash\ncd \npip install -r requirements.txt\n# or\npip install -e .\npython main.py\n```\n\n#### Java Projects\n```bash\ncd \nmvn clean install\nmvn spring-boot:run\n```\n\n## Development Workflow\n\n### MCP 7-28 Readiness\n\n#### Repo readiness checklist\n\n- [x] **New contributor clarity**: This file defines repository purpose,\n structure, contribution rules, and sample setup paths.\n- [x] **Build/test/lint commands with exact flags**:\n - Repository docs lint:\n `npx --yes markdownlint-cli2 \"**/*.md\" \"#node_modules\" \"#translations\" \"#translated_images\"`\n - Repository docs link pattern audit:\n `find . -name \"*.md\" -not -path \"*/node_modules/*\" -not -path \"./translations/*\" -not -path \"./translated_images/*\" -print0 | xargs -0 grep -En \"\\[.*\\]\\(.*\\)\"`\n - TypeScript sample validation:\n `cd 03-GettingStarted/samples/typescript && npm ci && npm test && npm run build`\n - Python sample validation:\n `cd 10-StreamliningAIWorkflowsBuildingAnMCPServerWithAIToolkit/lab3/code/weather_mcp && python -m pip install -e . && pytest -q`\n - Java sample validation:\n `cd 03-GettingStarted/samples/java/calculator && mvn -B -ntp test verify`\n- [x] **One realistic workflow that can become an MCP tool**:\n `validate_curriculum_change`\n- [x] **Inputs/outputs are explicit** (see specification below).\n- [x] **Permissions and failure modes are documented** (see specification below).\n- [x] **CI testability is explicit** (deterministic commands, explicit\n exit codes, and machine-readable outputs).\n\n#### Candidate MCP tool workflow: `validate_curriculum_change`\n\n##### Goal\n\nValidate curriculum documentation changes and representative sample code\nhealth before merge.\n\n##### Inputs\n\n- `changed_paths: string[]` (required) - relative paths changed in PR.\n- `run_docs_lint: boolean` (default `true`)\n- `run_links_audit: boolean` (default `true`)\n- `run_samples: { typescript?: boolean, python?: boolean, java?: boolean }`\n (default all `false`)\n\n##### Outputs\n\n- `status: \"ok\" | \"failed\"`\n- `checks: Array<{ name: string, command: string, exit_code: number,\n summary: string }>`\n- `artifacts: Array<{ type: \"log\" | \"report\", path: string }>`\n- `failed_checks: string[]`\n\n##### Permissions\n\n- Read workspace files and write tool-generated artifacts (e.g., lint\n reports, test logs) only; no writes to `translations/` or\n `translated_images/`.\n- Execute local shell commands.\n- Optional network access only for package restore (`npm ci`,\n `python -m pip install`, `mvn` dependency resolution).\n- No permission to push, merge, or modify `translations/` or\n `translated_images/`.\n\n##### Failure modes\n\n- `E_NO_INPUT_PATHS`: `changed_paths` empty.\n- `E_INVALID_PATH`: input path escapes repository root.\n- `E_LINT_FAILED`: markdown lint exits non-zero.\n- `E_LINK_AUDIT_FAILED`: link audit command exits non-zero.\n- `E_SAMPLE_TEST_FAILED`: sample test/build exits non-zero.\n- `E_TIMEOUT`: command exceeded configured timeout.\n\n##### Recommended CI contract\n\nTo automate validation, configure a CI job that:\n\n- Triggers on pull requests touching `*.md`, sample code, or this file.\n- Runs the exact commands listed above.\n- Persists logs as artifacts.\n- Fails the job on any non-zero exit code.\n\n#### If you ship an MCP server from this repo\n\n- [ ] Read the draft changelog for MCP 7-28:\n \n- [ ] Run your server against SDK betas:\n \n- [ ] Remove session and handshake assumptions; treat each request as\n self-contained:\n \n- [ ] Send `Mcp-Method` and `Mcp-Name` headers for raw HTTP requests:\n \n- [ ] Audit hardcoded error codes (`missing resource` moved from `-32002` to `-32602`).\n- [ ] Flag and plan migration for deprecated roots, sampling, and\n logging:\n \n- [ ] Migrate off the experimental `2025-11-25` Tasks API:\n \n- [ ] Review authorization for OAuth and OpenID Connect hardening:\n \n\n### Documentation Structure\n\n- **Modules 00-11**: Core curriculum content in sequential order\n- **translations/**: Language-specific versions (auto-generated, do not edit directly)\n- **translated_images/**: Localized image versions (auto-generated)\n- **images/**: Source images and diagrams\n\n### Making Documentation Changes\n\n1. Edit only the English markdown files in the root module directories (00-11)\n2. Update images in the `images/` directory if needed\n3. The co-op-translator GitHub Action will automatically generate translations\n4. Translations are regenerated on push to main branch\n\n### Working with Translations\n\n- **Automated Translation**: GitHub Actions workflow handles all translations\n- **Do NOT manually edit** files in `translations/` directory\n- Translation metadata is embedded in each translated file\n- Supported languages: 48+ languages including Arabic, Chinese, French, German, Hindi, Japanese, Korean, Portuguese, Russian, Spanish, and many more\n\n## Testing Instructions\n\n### Documentation Validation\n\nSince this is primarily a documentation repository, testing focuses on:\n\n1. **Link Pattern Audit**: List Markdown links for review\n\n ```bash\n # List Markdown links (pattern audit)\n find . -name \"*.md\" -not -path \"*/node_modules/*\" -not -path \"./translations/*\" -not -path \"./translated_images/*\" -print0 | xargs -0 grep -En \"\\[.*\\]\\(.*\\)\"\n ```\n\n2. **Code Sample Validation**: Test that code examples compile/run\n\n ```bash\n # Navigate to specific sample and run its tests\n cd 03-GettingStarted/samples/typescript\n npm install && npm test\n ```\n\n3. **Markdown Linting**: Check formatting consistency\n\n ```bash\n # Use markdownlint if needed\n npx --yes markdownlint-cli2 \"**/*.md\" \"#node_modules\" \"#translations\" \"#translated_images\"\n ```\n\n### Sample Project Testing\n\nEach language-specific sample includes its own testing approach:\n\n#### TypeScript/JavaScript\n```bash\nnpm test\nnpm run build\n```\n\n#### Python\n```bash\npytest\npython -m pytest tests/\n```\n\n#### Java\n```bash\nmvn test\nmvn verify\n```\n\n## Code Style Guidelines\n\n### Documentation Style\n\n- Use clear, beginner-friendly language\n- Include code examples in multiple languages where applicable\n- Follow markdown best practices:\n - Use ATX-style headers (`#` syntax)\n - Use fenced code blocks with language identifiers\n - Include descriptive alt text for images\n - Keep line lengths reasonable (no hard limit, but be sensible)\n\n### Code Sample Style\n\n#### TypeScript/JavaScript\n- Use ES modules (`import`/`export`)\n- Follow TypeScript strict mode conventions\n- Include type annotations\n- Target ES2022\n\n#### Python\n- Follow PEP 8 style guidelines\n- Use type hints where appropriate\n- Include docstrings for functions and classes\n- Use modern Python features (3.8+)\n\n#### Java\n- Follow Spring Boot conventions\n- Use Java 21 features\n- Follow standard Maven project structure\n- Include Javadoc comments\n\n### File Organization\n\n```\n-/\n├── README.md # Main module content\n├── samples/ # Code examples (if applicable)\n│ ├── typescript/\n│ ├── python/\n│ ├── java/\n│ └── ...\n└── solution/ # Complete working solutions\n └── /\n```\n\n## Build and Deployment\n\n### Documentation Deployment\n\nThe repository uses GitHub Pages or similar for documentation hosting (if applicable). Changes to the main branch trigger:\n\n1. Translation workflow (`.github/workflows/co-op-translator.yml`)\n2. Automated translation of all English markdown files\n3. Image localization as needed\n\n### No Build Process Required\n\nThis repository primarily contains markdown documentation. No compilation or build step is needed for the core curriculum content.\n\n### Sample Project Deployment\n\nIndividual sample projects may have deployment instructions:\n- See `03-GettingStarted/09-deployment/` for MCP server deployment guidance\n- Azure Container Apps deployment examples in `11-MCPServerHandsOnLabs/`\n\n## Contributing Guidelines\n\n### Pull Request Process\n\n1. **Fork and Clone**: Fork the repository and clone your fork locally\n2. **Create a Branch**: Use descriptive branch names (e.g., `fix/typo-module-3`, `add/python-example`)\n3. **Make Changes**: Edit English markdown files only (not translations)\n4. **Test Locally**: Verify markdown renders correctly\n5. **Submit PR**: Use clear PR titles and descriptions\n6. **CLA**: Sign the Microsoft Contributor License Agreement when prompted\n\n### PR Title Format\n\nUse clear, descriptive titles:\n- `[Module XX] Brief description` for module-specific changes\n- `[Samples] Description` for sample code changes\n- `[Docs] Description` for general documentation updates\n\n### What to Contribute\n\n- Bug fixes in documentation or code samples\n- New code examples in additional languages\n- Clarifications and improvements to existing content\n- New case studies or practical examples\n- Issue reports for unclear or incorrect content\n\n### What NOT to Do\n\n- Do not directly edit files in `translations/` directory\n- Do not edit `translated_images/` directory\n- Do not add large binary files without discussion\n- Do not change translation workflow files without coordination\n\n## Additional Notes\n\n### Repository Maintenance\n\n- **Changelog**: All significant changes are documented in `changelog.md`\n- **Study Guide**: Use `study_guide.md` for curriculum navigation overview\n- **Issue Templates**: Use GitHub issue templates for bug reports and feature requests\n- **Code of Conduct**: All contributors must follow the Microsoft Open Source Code of Conduct\n\n### Learning Path\n\nFollow modules in sequential order (00-11) for optimal learning:\n1. **00-02**: Fundamentals (Introduction, Core Concepts, Security)\n2. **03**: Getting Started with hands-on implementation\n3. **04-05**: Practical implementation and advanced topics\n4. **06-10**: Community, best practices, and real-world applications\n5. **11**: Comprehensive database integration labs (13 sequential labs)\n\n### Support Resources\n\n- **Documentation**: https://modelcontextprotocol.io/\n- **Specification**: https://spec.modelcontextprotocol.io/\n- **Community**: https://github.com/orgs/modelcontextprotocol/discussions\n- **Discord**: Microsoft Foundry Discord server\n- **Related Courses**: See README.md for other Microsoft learning paths\n\n### Common Troubleshooting\n\n**Q: My PR is failing the translation check**\nA: Ensure you only edited English markdown files in the root module directories, not translated versions.\n\n**Q: How do I add a new language?**\nA: Language support is managed through the co-op-translator workflow. Open an issue to discuss adding new languages.\n\n**Q: Code samples aren't working**\nA: Ensure you've followed the setup instructions in the specific sample's README. Check that you have the correct versions of dependencies installed.\n\n**Q: Images aren't displaying**\nA: Verify image paths are relative and use forward slashes. Images should be in the `images/` directory or `translated_images/` for localized versions.\n\n### Performance Considerations\n\n- Translation workflow may take several minutes to complete\n- Large images should be optimized before committing\n- Keep individual markdown files focused and reasonably sized\n- Use relative links for better portability\n\n### Project Governance\n\nThis project follows Microsoft open source practices:\n- MIT License for code and documentation\n- Microsoft Open Source Code of Conduct\n- CLA required for contributions\n- Security issues: Follow SECURITY.md guidelines\n- Support: See SUPPORT.md for help resources\n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","title":"AGENTS.md","content":"# AGENTS.md\n\n## Project Overview\n\n**MCP for Beginners** is an open-source educational curriculum for learning the Model Context Protocol (MCP) - a standardized framework for interactions between AI models and client applications. This repository provides comprehensive learning materials with hands-on code examples across multiple programming languages.\n\n### Key Technologies\n\n- **Programming Languages**: C#, Java, JavaScript, TypeScript, Python, Rust\n- **Frameworks & SDKs**: \n - MCP SDK (`@modelcontextprotocol/sdk`)\n - Spring Boot (Java)\n - FastMCP (Python)\n - LangChain4j (Java)\n- **Databases**: PostgreSQL with pgvector extension\n- **Cloud Platforms**: Azure (Container Apps, OpenAI, Content Safety, Application Insights)\n- **Build Tools**: npm, Maven, pip, Cargo\n- **Documentation**: Markdown with automated multi-language translation (48+ languages)\n\n### Architecture\n\n- **11 Core Modules (00-11)**: Sequential learning path from fundamentals to advanced topics\n- **Hands-on Labs**: Practical exercises with complete solution code in multiple languages\n- **Sample Projects**: Working MCP server and client implementations\n- **Translation System**: Automated GitHub Actions workflow for multi-language support\n- **Image Assets**: Centralized images directory with translated versions\n\n## Setup Commands\n\nThis is a documentation-focused repository. Most setup occurs within individual sample projects and labs.\n\n### Repository Setup\n\n```bash\n# Clone the repository\ngit clone https://github.com/microsoft/mcp-for-beginners.git\ncd mcp-for-beginners\n```\n\n### Working with Sample Projects\n\nSample projects are located in:\n- `03-GettingStarted/samples/` - Language-specific examples\n- `03-GettingStarted/01-first-server/solution/` - First server implementations\n- `03-GettingStarted/02-client/solution/` - Client implementations\n- `11-MCPServerHandsOnLabs/` - Comprehensive database integration labs\n\nEach sample project contains its own setup instructions:\n\n#### TypeScript/JavaScript Projects\n```bash\ncd \nnpm install\nnpm start\n```\n\n#### Python Projects\n```bash\ncd \npip install -r requirements.txt\n# or\npip install -e .\npython main.py\n```\n\n#### Java Projects\n```bash\ncd \nmvn clean install\nmvn spring-boot:run\n```\n\n## Development Workflow\n\n### MCP 7-28 Readiness\n\n#### Repo readiness checklist\n\n- [x] **New contributor clarity**: This file defines repository purpose,\n structure, contribution rules, and sample setup paths.\n- [x] **Build/test/lint commands with exact flags**:\n - Repository docs lint:\n `npx --yes markdownlint-cli2 \"**/*.md\" \"#node_modules\" \"#translations\" \"#translated_images\"`\n - Repository docs link pattern audit:\n `find . -name \"*.md\" -not -path \"*/node_modules/*\" -not -path \"./translations/*\" -not -path \"./translated_images/*\" -print0 | xargs -0 grep -En \"\\[.*\\]\\(.*\\)\"`\n - TypeScript sample validation:\n `cd 03-GettingStarted/samples/typescript && npm ci && npm test && npm run build`\n - Python sample validation:\n `cd 10-StreamliningAIWorkflowsBuildingAnMCPServerWithAIToolkit/lab3/code/weather_mcp && python -m pip install -e . && pytest -q`\n - Java sample validation:\n `cd 03-GettingStarted/samples/java/calculator && mvn -B -ntp test verify`\n- [x] **One realistic workflow that can become an MCP tool**:\n `validate_curriculum_change`\n- [x] **Inputs/outputs are explicit** (see specification below).\n- [x] **Permissions and failure modes are documented** (see specification below).\n- [x] **CI testability is explicit** (deterministic commands, explicit\n exit codes, and machine-readable outputs).\n\n#### Candidate MCP tool workflow: `validate_curriculum_change`\n\n##### Goal\n\nValidate curriculum documentation changes and representative sample code\nhealth before merge.\n\n##### Inputs\n\n- `changed_paths: string[]` (required) - relative paths changed in PR.\n- `run_docs_lint: boolean` (default `true`)\n- `run_links_audit: boolean` (default `true`)\n- `run_samples: { typescript?: boolean, python?: boolean, java?: boolean }`\n (default all `false`)\n\n##### Outputs\n\n- `status: \"ok\" | \"failed\"`\n- `checks: Array<{ name: string, command: string, exit_code: number,\n summary: string }>`\n- `artifacts: Array<{ type: \"log\" | \"report\", path: string }>`\n- `failed_checks: string[]`\n\n##### Permissions\n\n- Read workspace files and write tool-generated artifacts (e.g., lint\n reports, test logs) only; no writes to `translations/` or\n `translated_images/`.\n- Execute local shell commands.\n- Optional network access only for package restore (`npm ci`,\n `python -m pip install`, `mvn` dependency resolution).\n- No permission to push, merge, or modify `translations/` or\n `translated_images/`.\n\n##### Failure modes\n\n- `E_NO_INPUT_PATHS`: `changed_paths` empty.\n- `E_INVALID_PATH`: input path escapes repository root.\n- `E_LINT_FAILED`: markdown lint exits non-zero.\n- `E_LINK_AUDIT_FAILED`: link audit command exits non-zero.\n- `E_SAMPLE_TEST_FAILED`: sample test/build exits non-zero.\n- `E_TIMEOUT`: command exceeded configured timeout.\n\n##### Recommended CI contract\n\nTo automate validation, configure a CI job that:\n\n- Triggers on pull requests touching `*.md`, sample code, or this file.\n- Runs the exact commands listed above.\n- Persists logs as artifacts.\n- Fails the job on any non-zero exit code.\n\n#### If you ship an MCP server from this repo\n\n- [ ] Read the draft changelog for MCP 7-28:\n \n- [ ] Run your server against SDK betas:\n \n- [ ] Remove session and handshake assumptions; treat each request as\n self-contained:\n \n- [ ] Send `Mcp-Method` and `Mcp-Name` headers for raw HTTP requests:\n \n- [ ] Audit hardcoded error codes (`missing resource` moved from `-32002` to `-32602`).\n- [ ] Flag and plan migration for deprecated roots, sampling, and\n logging:\n \n- [ ] Migrate off the experimental `2025-11-25` Tasks API:\n \n- [ ] Review authorization for OAuth and OpenID Connect hardening:\n \n\n### Documentation Structure\n\n- **Modules 00-11**: Core curriculum content in sequential order\n- **translations/**: Language-specific versions (auto-generated, do not edit directly)\n- **translated_images/**: Localized image versions (auto-generated)\n- **images/**: Source images and diagrams\n\n### Making Documentation Changes\n\n1. Edit only the English markdown files in the root module directories (00-11)\n2. Update images in the `images/` directory if needed\n3. The co-op-translator GitHub Action will automatically generate translations\n4. Translations are regenerated on push to main branch\n\n### Working with Translations\n\n- **Automated Translation**: GitHub Actions workflow handles all translations\n- **Do NOT manually edit** files in `translations/` directory\n- Translation metadata is embedded in each translated file\n- Supported languages: 48+ languages including Arabic, Chinese, French, German, Hindi, Japanese, Korean, Portuguese, Russian, Spanish, and many more\n\n## Testing Instructions\n\n### Documentation Validation\n\nSince this is primarily a documentation repository, testing focuses on:\n\n1. **Link Pattern Audit**: List Markdown links for review\n\n ```bash\n # List Markdown links (pattern audit)\n find . -name \"*.md\" -not -path \"*/node_modules/*\" -not -path \"./translations/*\" -not -path \"./translated_images/*\" -print0 | xargs -0 grep -En \"\\[.*\\]\\(.*\\)\"\n ```\n\n2. **Code Sample Validation**: Test that code examples compile/run\n\n ```bash\n # Navigate to specific sample and run its tests\n cd 03-GettingStarted/samples/typescript\n npm install && npm test\n ```\n\n3. **Markdown Linting**: Check formatting consistency\n\n ```bash\n # Use markdownlint if needed\n npx --yes markdownlint-cli2 \"**/*.md\" \"#node_modules\" \"#translations\" \"#translated_images\"\n ```\n\n### Sample Project Testing\n\nEach language-specific sample includes its own testing approach:\n\n#### TypeScript/JavaScript\n```bash\nnpm test\nnpm run build\n```\n\n#### Python\n```bash\npytest\npython -m pytest tests/\n```\n\n#### Java\n```bash\nmvn test\nmvn verify\n```\n\n## Code Style Guidelines\n\n### Documentation Style\n\n- Use clear, beginner-friendly language\n- Include code examples in multiple languages where applicable\n- Follow markdown best practices:\n - Use ATX-style headers (`#` syntax)\n - Use fenced code blocks with language identifiers\n - Include descriptive alt text for images\n - Keep line lengths reasonable (no hard limit, but be sensible)\n\n### Code Sample Style\n\n#### TypeScript/JavaScript\n- Use ES modules (`import`/`export`)\n- Follow TypeScript strict mode conventions\n- Include type annotations\n- Target ES2022\n\n#### Python\n- Follow PEP 8 style guidelines\n- Use type hints where appropriate\n- Include docstrings for functions and classes\n- Use modern Python features (3.8+)\n\n#### Java\n- Follow Spring Boot conventions\n- Use Java 21 features\n- Follow standard Maven project structure\n- Include Javadoc comments\n\n### File Organization\n\n```\n-/\n├── README.md # Main module content\n├── samples/ # Code examples (if applicable)\n│ ├── typescript/\n│ ├── python/\n│ ├── java/\n│ └── ...\n└── solution/ # Complete working solutions\n └── /\n```\n\n## Build and Deployment\n\n### Documentation Deployment\n\nThe repository uses GitHub Pages or similar for documentation hosting (if applicable). Changes to the main branch trigger:\n\n1. Translation workflow (`.github/workflows/co-op-translator.yml`)\n2. Automated translation of all English markdown files\n3. Image localization as needed\n\n### No Build Process Required\n\nThis repository primarily contains markdown documentation. No compilation or build step is needed for the core curriculum content.\n\n### Sample Project Deployment\n\nIndividual sample projects may have deployment instructions:\n- See `03-GettingStarted/09-deployment/` for MCP server deployment guidance\n- Azure Container Apps deployment examples in `11-MCPServerHandsOnLabs/`\n\n## Contributing Guidelines\n\n### Pull Request Process\n\n1. **Fork and Clone**: Fork the repository and clone your fork locally\n2. **Create a Branch**: Use descriptive branch names (e.g., `fix/typo-module-3`, `add/python-example`)\n3. **Make Changes**: Edit English markdown files only (not translations)\n4. **Test Locally**: Verify markdown renders correctly\n5. **Submit PR**: Use clear PR titles and descriptions\n6. **CLA**: Sign the Microsoft Contributor License Agreement when prompted\n\n### PR Title Format\n\nUse clear, descriptive titles:\n- `[Module XX] Brief description` for module-specific changes\n- `[Samples] Description` for sample code changes\n- `[Docs] Description` for general documentation updates\n\n### What to Contribute\n\n- Bug fixes in documentation or code samples\n- New code examples in additional languages\n- Clarifications and improvements to existing content\n- New case studies or practical examples\n- Issue reports for unclear or incorrect content\n\n### What NOT to Do\n\n- Do not directly edit files in `translations/` directory\n- Do not edit `translated_images/` directory\n- Do not add large binary files without discussion\n- Do not change translation workflow files without coordination\n\n## Additional Notes\n\n### Repository Maintenance\n\n- **Changelog**: All significant changes are documented in `changelog.md`\n- **Study Guide**: Use `study_guide.md` for curriculum navigation overview\n- **Issue Templates**: Use GitHub issue templates for bug reports and feature requests\n- **Code of Conduct**: All contributors must follow the Microsoft Open Source Code of Conduct\n\n### Learning Path\n\nFollow modules in sequential order (00-11) for optimal learning:\n1. **00-02**: Fundamentals (Introduction, Core Concepts, Security)\n2. **03**: Getting Started with hands-on implementation\n3. **04-05**: Practical implementation and advanced topics\n4. **06-10**: Community, best practices, and real-world applications\n5. **11**: Comprehensive database integration labs (13 sequential labs)\n\n### Support Resources\n\n- **Documentation**: https://modelcontextprotocol.io/\n- **Specification**: https://spec.modelcontextprotocol.io/\n- **Community**: https://github.com/orgs/modelcontextprotocol/discussions\n- **Discord**: Microsoft Foundry Discord server\n- **Related Courses**: See README.md for other Microsoft learning paths\n\n### Common Troubleshooting\n\n**Q: My PR is failing the translation check**\nA: Ensure you only edited English markdown files in the root module directories, not translated versions.\n\n**Q: How do I add a new language?**\nA: Language support is managed through the co-op-translator workflow. Open an issue to discuss adding new languages.\n\n**Q: Code samples aren't working**\nA: Ensure you've followed the setup instructions in the specific sample's README. Check that you have the correct versions of dependencies installed.\n\n**Q: Images aren't displaying**\nA: Verify image paths are relative and use forward slashes. Images should be in the `images/` directory or `translated_images/` for localized versions.\n\n### Performance Considerations\n\n- Translation workflow may take several minutes to complete\n- Large images should be optimized before committing\n- Keep individual markdown files focused and reasonably sized\n- Use relative links for better portability\n\n### Project Governance\n\nThis project follows Microsoft open source practices:\n- MIT License for code and documentation\n- Microsoft Open Source Code of Conduct\n- CLA required for contributions\n- Security issues: Follow SECURITY.md guidelines\n- Support: See SUPPORT.md for help resources\n","category":"root","tokens":3522}]}